Add Dewey to an existing repository without replacing its documentation

An established repository already contains decisions about how to work: rules in AGENTS.md, setup instructions in Markdown, and perhaps a skill that another agent uses to consume the project. Adding a documentation tool should preserve that knowledge and make its maintenance easier.

Dewey 0.5.1 can initialize a repository that already has documentation. It retains authored text, adds managed regions where needed, and classifies existing pages for its documentation model. Review the diff, especially classifications inferred from file paths. Initialization behavior

Here is what adoption changes, using a small existing repository as a concrete example.

Inventory what is already authoritative

Before running init, locate the files that hold the project's rules, setup instructions, public interface, and implementation notes. Check the working tree so you can distinguish existing edits from the adoption diff:

git status --shortgit diff

The example starts with four authored files:

File	Existing material
AGENTS.md	A rule to keep the public return type stable
llms.txt	A maintained introduction
docs/quickstart.md	A short setup guide without frontmatter
SKILL.md	Instructions for consumers of the project

There is also src/index.ts, which exports a version constant. The fixture's package is private, so package-publication requirements do not apply to this example.

In a real repository, decide which instructions remain authoritative before generating more files. Conflicting rules need an editorial decision; a successful initialization cannot choose between them for you.

Initialize with the project's purpose

Install the tested release and run init from the project root:

bun add -d @deweydocs/dewey@0.5.1bunx dewey init \  --purpose "Demonstrate documentation adoption" \  --no-rules

The example uses --no-rules because it supplies no additional rules through the initializer. The authored AGENTS.md rule remains in place. For another project, use its actual purpose and repeat --rule for the rules you want to supply. Quickstart options

Init reports the files it adopted. The observed changes in this example were:

File	Result
AGENTS.md	Original text retained; a managed observed region appended
llms.txt	Original text retained; a managed index region appended
docs/quickstart.md	Original body retained; kind: guide frontmatter added
SKILL.md	Byte-for-byte unchanged

The quickstart's body was preserved, but the file was not identical. Dewey added metadata so it could classify and publish the page. That is the distinction to look for in the diff.

Review the classification, not just the prose

The original quickstart began:

# Start hereRead the example before making changes.

After initialization it began:

---kind: guide---# Start hereRead the example before making changes.

Dewey infers kinds for existing documents without them. Files under reference or API paths become references. Files under plans, specs, reports, proposals, or decisions become history. Other documentation becomes a guide.

Those guesses are a starting point. A page in docs/ might be an abandoned design, even if its filename looks like a current task. Read the classified documents and correct their metadata. Guides and references can appear on the generated site; maps and history are excluded from that build. Anyone with repository access can still read those files.

Complete the new maintenance structure

Adoption also creates the project settings, authoring skill, and any needed source-map drafts. The existing quickstart is preserved, so it does not need to be replaced with a new scaffold.

Read each new map against the source it covers. Name the files, explain the data flow, and record the invariants and traps. Remove draft: true when the map is finished, then record the review:

bunx dewey review docs/src.agent.mdbunx dewey buildbunx dewey check

Use the actual map path for your repository. dewey uncovered identifies source files without maps, and dewey which <path> finds the documents that cover a particular source file.

A passing check establishes consistency among references, coverage, reviews, and outputs. It does not certify the quality of the existing guide. Preserve useful writing, then improve any instructions whose result a reader cannot verify.

Resolve a conflict at its source

Init has explicit failure boundaries. For example, in an uninitialized project it refuses an existing .dewey/site/ or .dewey/outputs.json. That state needs inspection before adoption can proceed. Determine which workflow created those files and whether they belong to the project you are initializing.

The current initializer restores files it touched if initialization fails. Even with that protection, inspect the working tree after a failure and resolve the reported cause before retrying. Keep authored text outside the managed regions so later builds can update observed facts without taking ownership of your rules.

Finish by reviewing the adoption diff, the new source maps, and the generated site's navigation. Use the CLI reference for initialization and ownership rules this example does not exercise.