Dewey article examples
Verified release: @deweydocs/dewey@0.5.1
Prerequisites: Bun and Python 3. Run commands in a disposable directory.

The fixtures contain only authored inputs. There are no installed dependencies,
generated sites, review hashes, credentials, or precomputed passing states.
The retry fixture includes finished documents; init still needs an explicit
review before check can pass. Install lifecycle scripts are disabled.

From the extracted examples directory, set the source directory and copy the retry fixture:

evidence_dir="$PWD"
retry_trial=$(mktemp -d -t dewey-retry-repro)
cp -R "$evidence_dir/fixtures/retry-baseline/." "$retry_trial"
cd "$retry_trial"
bun install --ignore-scripts
bunx dewey --version
bun run demo
bunx dewey init --purpose "Print the retry budget" --rule "Keep the retry budget in src/retry.ts"
bunx dewey check --json

Expected: version 0.5.1; demo prints "Maximum attempts: 3".
The initial check exits 1 with REVIEW_REQUIRED because the authored map has
not been reviewed yet. This is an expected failure, not a setup error.

Read src/index.ts and src/retry.ts and compare them to docs/src.agent.md.
Then record the review and build:

bunx dewey review docs/src.agent.md
bunx dewey build
bunx dewey check --json
bunx dewey which src/retry.ts --json
bunx dewey uncovered --json

Expected: check returns { "passed": true, "issues": [] }; which finds the map;
uncovered returns an empty areas array. AGENTS.md contains 24 lines. The
authored map has 20 lines and which estimates 103 tokens for it.

Change the behavior while leaving the documents at the reviewed baseline:

python3 - <<'PY'
from pathlib import Path
Path('src/retry.ts').write_text('export const maxAttempts = 5\n')
PY
bun run demo
bunx dewey build
bunx dewey check --json

Expected: the demo prints "Maximum attempts: 5". Build succeeds. Check exits 1
with REVIEW_REQUIRED on docs/src.agent.md and names changed: src/retry.ts.
Build does not acknowledge a documentation review.

After inspecting that source change, correct both affected documents:

python3 - <<'PY'
from pathlib import Path
path = Path('docs/src.agent.md')
path.write_text(path.read_text().replace('currently 3', 'currently 5'))
path = Path('docs/quickstart.md')
path.write_text(path.read_text().replace('attempts: 3', 'attempts: 5'))
PY
bunx dewey review docs/src.agent.md
bunx dewey build
bunx dewey check --json

Expected: check passes again. The review signal names the covered map; updating
the related quickstart is an editorial action, not an automatic semantic fix.

Inspect these generated files:

.dewey/site/docs/quickstart.html
.dewey/site/docs/quickstart.md
.dewey/site/llms.txt
.dewey/site/llms-full.txt
.dewey/site/nav.json

Both page representations contain the expected output of 5. The site index
links to docs/quickstart.md and includes its summary and estimated size.
The source map's "Retry implementation" body is absent from llms-full.txt.
The source map itself remains at docs/src.agent.md in the repository.

Adoption example

The second fixture starts with authored AGENTS.md, llms.txt, SKILL.md and a
quickstart without frontmatter. Copy it separately:

adoption_trial=$(mktemp -d -t dewey-adoption-repro)
cp -R "$evidence_dir/fixtures/adoption-inputs/." "$adoption_trial"
cd "$adoption_trial"
bun install --ignore-scripts
bunx dewey init --purpose "Demonstrate documentation adoption" --no-rules
diff -u "$evidence_dir/fixtures/adoption-inputs/AGENTS.md" AGENTS.md
diff -u "$evidence_dir/fixtures/adoption-inputs/llms.txt" llms.txt
diff -u "$evidence_dir/fixtures/adoption-inputs/docs/quickstart.md" docs/quickstart.md
diff -u "$evidence_dir/fixtures/adoption-inputs/SKILL.md" SKILL.md

Expected: init exits 0. AGENTS.md and llms.txt retain their original text and
gain managed regions. The quickstart gains kind: guide frontmatter and keeps
its body. SKILL.md is unchanged. The first three diff commands therefore exit
1 to indicate differences; the SKILL.md diff exits 0. The new source map is a
draft and must be authored and reviewed before a passing check is expected.

To reproduce the fresh-scaffold DOC_DRAFT result, start
another empty temporary directory, copy only retry-baseline/package.json and
retry-baseline/src into it, install with --ignore-scripts, and run the same
init and check commands. Dewey creates draft guide/map files in that case.

Reproduction should create new temporary directories; do not run the experiment inside an existing product checkout.
