One Documentation Root: docs/ becomes documentation/ in 2.49.0

Datarim 2.49.0 makes one structural change and commits to it everywhere: the documentation root is renamed from docs/ to documentation/. It is a breaking change to the canon, so it is worth explaining why a folder rename earned a minor-version bump and a hard-flip compatibility rule.

The problem: two folders, two meanings, one collision waiting to happen

A Datarim project actually had two documentation surfaces that lived under different names and never reconciled:

• docs/ — the framework’s own product documentation: getting-started, the command and skill reference, the explanation pieces.
• documentation/ — the consumer’s knowledge base: archived task records, mandates, infrastructure notes — the committed history of a project that uses Datarim.

Two roots, two contracts, no shared vocabulary. Every new project had to learn that “docs” meant one thing inside the framework and that its own long-term documentation went somewhere else entirely. The drift detector could see a project had a docs/ folder but had no opinion about how it related to documentation/. The split was a small tax paid on every repo, forever.

The decision: rename and merge under one root

Rather than keep two names, 2.49.0 makes documentation/ the single canonical documentation root for the whole ecosystem. The framework’s product docs move into it, organised by the four Diátaxis categories:

• documentation/tutorials/ — learning-oriented walkthroughs (getting-started, use-cases)
• documentation/how-to/ — task-oriented recipes (release process, verification, the evolution log)
• documentation/reference/ — information-oriented lookups (commands, skills, the CLI, the validator contract)
• documentation/explanation/ — understanding-oriented background (the pipeline, consilium, spec-traceability)

The consumer’s existing knowledge base does not move — its task archive stays at documentation/archive/. The renamed product docs simply become siblings of it. To keep the two contracts from colliding again, four names are now reserved: a Diátaxis category may not be called archive, evolution, release-audit, or ephemeral. One root, clearly partitioned, no overlap.

Git history is preserved throughout — every file moves with git mv, so git log --follow still reaches back past the rename.

Hard-flip — but never a reproach without a remedy

The compatibility stance is a clean break: the drift detector now treats a repo still on legacy docs/ as drift. A hard flip is only fair if the thing it flags can actually be fixed — flagging a problem with no fix path is just nagging. So 2.49.0 ships the remedy in the same release.

/dr-doctor gains an opt-in documentation-migration self-heal pass. Point it at a consumer repo still on docs/ and it performs the same migration the framework did to itself:

• Detect the layout — legacy docs/, a partial half-migrated state, or an already-migrated repo (in which case it is a clean no-op).
• Migrate with git mv + the Diátaxis split (known files map to their category; unknown files land in how-to/ with a review marker) + an anchored reference rewrite.
• Verify the result against the reference linter — and if any check fails, roll back to the exact pre-migration tree from a backup tarball.

It is idempotent (run it twice, the second run does nothing) and rollback-safe (a failed verify never leaves you half-migrated). Deliberately, it is a separate sibling tool, not a new mode bolted onto the operational-file doctor — product-docs live physically outside the framework’s own state directory, and mixing a content migration into a schema migration would blur a boundary the framework keeps on purpose.

How to migrate your repo

If your project still uses docs/, the upgrade is one opt-in command:

• Run /dr-doctor; it reports legacy docs/ as an available migration.
• Accept the migration; the doctor moves your docs into documentation/ with the Diátaxis split and rewrites references.
• If a post-migration check fails, the tree is restored automatically — nothing is left half-done.

New projects scaffolded by /dr-init already start with documentation/. Nothing to do there.

Why this matters

The change is small in diff and large in clarity. One documentation root means there is exactly one answer to “where does this document go?” — product docs by Diátaxis category, project history under archive/, both under documentation/. The drift detector, the scaffold, the mandates, and the doctor now all point at the same place. See the changelog for the full entry.