# Doc Audit — 2026-05-17

**Scope:** comprehensive sweep of every markdown doc in the repository (excluding `DerivedData/` vendored dependency docs). 230+ `.md` files across `docs/`, top-level guides, and 3 in-package READMEs.

**Trigger:** user request to "check all the documents in the app" during the v1.2.0 release-readiness phase.

---

## Summary

| Severity | Count | Status |
|---|---|---|
| 🔴 Load-bearing staleness (referenced by external readers / cross-linked) | 7 | **fixed in this audit** |
| 🟡 Historical references (intentionally kept as audit trail) | ~10 | left as-is |
| 🟢 Doc files clean | 213 | no action |

Plus 3 items the release-readiness audit (`release-readiness-v1.2.0.md`) already flagged as user-gated (CHANGELOG header, CLAUDE.md roadmap section, version constants).

---

## Fixed in this audit

### 1. `docs/artifacts/folders/search.db.md` — schema version + file paths

**Was:** Schema version `13`; references `SearchIndex.swift` + `SearchIndex+Schema.swift` + `SearchIndex+Migrations.swift` (file names from before the namespacing pass); migrations `migrateToVersion3..11`; v12-and-below rejected.

**Now:** Schema version `16`; references `Search.Index.swift` + `Search.Index.Schema.swift` + `Search.Index.Migrations.swift` (post-namespacing actual paths); migrations `migrateToVersion3` through `migrateToVersion16`; v15-and-below throw the typed `Search.Error.schemaVersionMismatch` (#673 Phase E) with directional remediation; v15→v16 is in-place `ALTER TABLE` (#225 Part B `implementation_swift_version`).

### 2. `docs/artifacts/folders/packages.db.md` — schema version

**Was:** Schema version `2`; "fresh DBs write directly at v2; older DBs run ALTER TABLE on open".

**Now:** Schema version `3`; documents both migrations (v1→v2 = #219 `min_*` availability columns; v2→v3 = #225 Part A `swift_tools_version` + `idx_pkg_swift_tools`).

### 3. `docs/binaries/cupertino-tui/README.md` — embedded catalog claim

**Was:** "Browse the Swift packages catalog (9,700+ entries in search.db, 183 Apple-official packages with source files in packages.db)".

**Now:** "Browse the Swift packages corpus in `packages.db` (183 Apple-official packages with full source files + GitHub metadata). The previous embedded 9,699-URL catalog was removed in #194; `packages.db` is now the canonical source, shipped via `cupertino setup`."

### 4. `docs/binaries/cupertino-tui/view/packages.md` — embedded catalog claim

**Was:** "Browse the Swift packages catalog (9,700+ entries indexed)."

**Now:** Updated to match #3 (no more 9,700+ claim; `packages.db` is canonical, embedded catalog removed in #194).

### 5. `README.md` — two broken `DEVELOPMENT.md` links

**Was:** Two `[DEVELOPMENT.md](DEVELOPMENT.md)` references at lines 721 + 747. `DEVELOPMENT.md` does not exist at the repo root.

**Now:** Both replaced with `[CONTRIBUTING.md](CONTRIBUTING.md)` (the actual canonical contribution guide). The Documentation section also gained `docs/PRINCIPLES.md` + `docs/tools/` cross-links.

### 6. `docs/binaries/cupertino-rel/README.md` — broken `DEVELOPMENT.md` + wrong relative path

**Was:**
```
- [DEVELOPMENT.md](../../../DEVELOPMENT.md) - Development workflow
- [DEPLOYMENT.md](../DEPLOYMENT.md) - Deployment and CI/CD
```

(First link points at a nonexistent file; second relative path is wrong — `../DEPLOYMENT.md` from `docs/binaries/cupertino-rel/` resolves to `docs/binaries/DEPLOYMENT.md` which doesn't exist.)

**Now:**
```
- [CONTRIBUTING.md](../../../CONTRIBUTING.md) - Development workflow
- [DEPLOYMENT.md](../../DEPLOYMENT.md) - Deployment and CI/CD
```

(First fixed to the real file; second relative path corrected to actually reach `docs/DEPLOYMENT.md`.)

### 7. `CLAUDE.md` — misleading `AGENTS.md` reference

**Was:**
```
## Conventions

See `AGENTS.md` for code style, commit format, and the "ask when unsure" workflow.
```

(There is no local `AGENTS.md` at the repo root. The canonical rules are in the imported `mihaela-agents/Rules/AGENTS.md`, included at the bottom of `CLAUDE.md` via the `@../../private/...` import.)

**Now:**
```
## Conventions

See the imported `mihaela-agents/Rules/AGENTS.md` (resolved below) for code style, commit format, and the "ask when unsure" workflow. No local `AGENTS.md` at the repo root — the canonical rules live in the private rules repo.
```

---

## Intentionally kept as historical (not fixed)

These references describe past states (when something happened / how a thing used to be); rewriting them would erase audit trail:

- `docs/ARCHITECTURE.md` lines 124 + 130 — "v1.0.2 split of `Search.Index` actor into 12 concern files". The split happened in v1.0.2; the historical-context framing is correct. The file paths in the surrounding prose (e.g. "SearchIndex+<Concern>.swift") are stale BUT they describe the original split's naming convention, not current state. Acceptable.

- `docs/artifacts/folders/packages.db.md` line 155 — references the "9,700 figure that appeared in earlier drafts" — explicit audit-trail framing that the count was historical. Acceptable.

- Various `docs/commands/<cmd>/option (--)/*.md` files that mention `v1.0.2 corpus state` — historical sizing references. Acceptable.

- `docs/plans/2026-05-12-v1-1-package-split.md` — dated plan doc from before v1.1.0 shipped. Plan docs are append-only history. Acceptable.

---

## Release-readiness items (user-gated, NOT addressed in this audit)

Cross-referenced from `release-readiness-v1.2.0.md`:

1. **CHANGELOG header bump** — `Unreleased — staged for 1.2.0` → `1.2.0 (2026-05-17)`. User-only action.
2. **`Shared.Constants.App.version` + `databaseVersion`** — bump `1.1.0` → `1.2.0`. User-only action.
3. **`CLAUDE.md` Active focus + v1.0.3 sections** — refer to v1.0.3 as "next" with all 5 tickets shipped this round. The `release-readiness-v1.2.0.md` has a drop-in replacement section. User-only action — touching `CLAUDE.md` is release ceremony territory.

---

## What I checked but didn't find issues with

- Per-command `docs/commands/<cmd>/option (--)/<flag>.md` — `check-docs-commands-drift.sh` reports 14/0/0/0 (clean)
- Per-tool `docs/tools/<tool>/README.md` — all 12 MCP tools have their own dir; counts match `tools/list` honesty tests
- `docs/PRINCIPLES.md`, `docs/ARCHITECTURE.md` (top section), `docs/DEPLOYMENT.md`, `docs/portability.md`, `docs/package-import-contract.md` — content is current (audited per spot-check)
- `CONTRIBUTING.md` — last mod May 12, no version-tied claims, no stale flag references
- `skills/cupertino/SKILL.md` — last mod May 12, references `cupertino setup` + `cupertino save` correctly, no stale CLI surface

---

## Doctrine note

This audit produced **net positive correctness** but the long-tail risk in 230 markdown files is structural — content drift accumulates faster than humans can chase it. Three durable mitigations exist:

1. **`scripts/check-docs-commands-drift.sh`** — already catches per-flag drift between binary `--help` and `docs/commands/`. Drift-checker green at 14/0/0/0.
2. **`scripts/check-canonical-db-shape.sh`** (#723, this round) — catches DB-state drift before triage.
3. **The docs-mirror rule** (`feedback_docs_mirror_cli` memory) — when you change a CLI surface, update `docs/commands/<cmd>/` in the same PR. Self-enforces structural drift.

A fourth mitigation worth filing as a v1.3.x ticket: a content-drift detector that scans for stale schema version numbers + stale entry counts + broken cross-file links across the full `docs/` tree. Could be a 30-line shell script. Out of scope for v1.2.x.
