---
type: types/instruction.md
name: 9.0.0-docs-diataxis
description: Point every file this instance owns at the explanation pages' new home under docs/explanation/ - a path rewrite with no judgment call, without which docs verify reports a dead link in kb/CONVENTIONS.md.
manual: true
migrates_to: 9.0.0
migration_kind: mechanical
obligation: required
---
# Point own files at `docs/explanation/` (9.0.0)

9.0.0 sorts the stack's human documentation under `docs/` into areas - `docs/tutorials/`,
`docs/how-to/`, `docs/reference/` and `docs/explanation/` - and moves the seven pages that used
to sit directly in `docs/` into `docs/explanation/`, names unchanged. Nothing is left at the old
paths: `dist upgrade` deletes them as files the release no longer ships.

Every file the stack ships already points at the new paths. A file **this instance owns** does
not, because an upgrade never touches it - and one such file is in every instance:
`kb/CONVENTIONS.md`, adopted from a template that linked `language-boundaries.md` at its old
place directly under `docs/`.
`tools/wikitool docs verify` checks every relative link in it, so after the upgrade it reports
that link as not resolving. This migration rewrites the old paths, and nothing else.

It is `mechanical`: the seven names map one to one, and there is no per-file judgment beyond
which files are in scope (§ Decision points).

<!-- wikitool:toc -->
## Contents

- [When to run](#when-to-run)
- [Steps](#steps)
- [How to tell a migrated file from an unmigrated one](#how-to-tell-a-migrated-file-from-an-unmigrated-one)
- [Decision points](#decision-points)
- [Scope](#scope)
<!-- /wikitool:toc -->

## When to run

After installing 9.0.0 machinery over an instance on 8.x - step 12 of
[upgrade-instance.md](../upgrade-instance.md), once `tools/wikitool migrate status` names this
document. Until it has run, `docs verify` reports the dead link in `kb/CONVENTIONS.md`; that
failure is expected between the machinery swap and this migration, and nothing else depends on
it.

## Steps

1. **Capture the baseline**, before changing anything - the list of every file this instance
   tracks that names an old path, and what `docs verify` says about it now:

   ```bash
   git grep -nE 'docs/(pipeline-rationale|ownership-and-templates|language-boundaries|why-gates-are-code|version-model|knowledge-and-commitment|model-and-effort-selection)\.md' -- . ':!raw' ':!CHANGES.md' ':!kb/log.md' > /tmp/9.0.0-before.txt
   tools/wikitool docs verify > /tmp/9.0.0-verify-before.txt
   ```

   Expect at least `kb/CONVENTIONS.md` in the first file and its dead link in the second.

2. **Decide which hits are in scope.** Every hit is, except a `kb/` page (a file under a
   collection with a `type:` in its frontmatter) - see § Decision points. In a typical instance
   the in-scope list is `kb/CONVENTIONS.md` alone; an instruction, a type-spec or a
   `COLLECTION.md` the instance wrote for itself may add to it.

3. **Rewrite the old paths in each in-scope file:**

   ```bash
   sed -i -E 's#docs/(pipeline-rationale|ownership-and-templates|language-boundaries|why-gates-are-code|version-model|knowledge-and-commitment|model-and-effort-selection)\.md#docs/explanation/\1.md#g' <file> ...
   ```

   The rewrite keeps everything before `docs/` - a link's `../` stays as it was, because only
   the part below `docs/` moved. No other line of the file changes.

4. **Check it against the baseline:**

   ```bash
   git diff --stat
   git grep -nE 'docs/(pipeline-rationale|ownership-and-templates|language-boundaries|why-gates-are-code|version-model|knowledge-and-commitment|model-and-effort-selection)\.md' -- . ':!raw' ':!CHANGES.md' ':!kb/log.md'
   tools/wikitool docs verify
   ```

   `git diff --stat` names exactly the files step 2 put in scope, one or a few lines each. The
   `git grep` prints only `kb/` pages step 2 left out - none at all in a typical instance. `docs
   verify` is green; compared with `/tmp/9.0.0-verify-before.txt`, the dead-link lines are what
   disappeared.

5. **Record it:**

   ```bash
   tools/wikitool migrate done 9.0.0 --pages 0
   ```

   `--pages 0` because no `kb/` page changes. The migration is `required`, so this advances
   `kb_version`.

## How to tell a migrated file from an unmigrated one

An unmigrated file names `docs/<one of the seven names>.md`; a migrated one names
`docs/explanation/<name>.md`. Step 4's `git grep` lists every file still waiting, and `docs verify`
names each unmigrated reference file by line.

## Decision points

- **A `kb/` page mentions an old path?** Leave it out of this migration: a page records
  what a source said at the time, `docs verify` does not read page bodies, and a page is changed
  through `wiki-manage`, not by `sed`. Update it the next time the page is worked on, if the
  mention is meant as a pointer rather than as evidence.
- **The instance links one of the pages under a different spelling** - an absolute URL into
  the origin repository, say? Out of scope: such a link never resolved inside the instance, and
  `docs verify` does not check it.

## Scope

Files this instance tracks that name one of the seven old paths, outside `raw/` (immutable),
`CHANGES.md` and `kb/log.md` (records of what was true at the time) and `kb/` pages. The
machinery itself - the moved pages, the new area READMEs, every shipped file that links them -
arrived with `dist upgrade` and needs nothing from this document.