Skip to content

docs: Compact the developer docs and drop unreferenced PR assets - #1093

Merged
omesser merged 2 commits into
mainfrom
docs/compact
Sep 28, 2026
Merged

omesser merged 2 commits into
mainfrom
docs/compact

Conversation

@omesser

@omesser omesser commented Sep 28, 2026 •

Copy link
Copy Markdown
Owner

Why

The docs had grown restatements, narrative history, and stale claims. The stale ones: Capture boxes in the design diagram, "two shipped Characters", Windows listed as deferred, and a checklist item that contradicts capturable-by-default. docs/pr/ and docs/pr-assets/ also held about 10 MB of one-off PR screenshots that nothing references.

What changed

File Before After Cut
docs/DEVELOPMENT.md 53.4 KB 38.6 KB Duplicate Trace Variables table and signing section merged. A broken FIDGET_CAPTURABLE paragraph and a checklist ref to nonexistent items 24–27 fixed. The dead "archived README lines 450–490" link now names the ignored test and pins the pre-#135 README. The MCP tool list defers to the README catalog. The cursor-agent, probe, and BYO prose is compacted. Every command, env var, and default stays.
README.md (after the opening) 24.6 KB 22.9 KB Feature bullets that #1091's opening covers. Harness-row history. A Harness ↔ MCP transport list that repeated footnote †. The unused in progress legend.
DESIGN.md 38.3 KB 37.5 KB Dropped Capture from the diagram, consent, denylist, and injection risks. Fixed the stale Character and animation counts and "Windows deferred". Trimmed narrative.
docs/SPEC.md 35.6 KB 34.9 KB Windows no longer deferred. Screen-share story and hide rules now match ADR-0024. "Window titles deferred" removed (ADR-0032). Build-order and "new repository" history cut.
docs/agents/*.md 20.1 KB 18.5 KB Multi-context scaffold in domain.md, dated history in picking-work.md, writing.md, and comments.md.
docs/pr/, docs/pr-assets/, 6 docs/readme/ PNGs ~10.6 MB deleted Unreferenced in the tree. Most PR bodies link these images at a commit SHA, so they still render. #594 linked blob/main/docs/pr/441-bubble-ceiling.png; its body now pins that link to 3d16d6fc.
docs/research/naming-review-2026-09.md 7.1 KB 7.2 KB Kept, with a preamble line saying the rename shipped in #1079 (docs/agents/docs.md).
scripts/verify-overlay.sh Its two pointers to the manual checklist now name docs/DEVELOPMENT.md instead of the README (#1094).

Left alone:

  • The rest of docs/research/. Research stays pinned to the tree it read (docs/agents/docs.md).
  • docs/design/ and spike/: out of scope for this PR.
  • The omesser/ai-buddy URLs, which fix: Point forge coordinates at omesser/fidget #1087 owns.
  • CONTEXT.md, which has no duplicates.

The ADR citations here already match #1092's replacement links for the ADRs it removes, and none point at a removed ADR. #1092 renumbers nothing. After either PR merges, the other conflicts in docs/DEVELOPMENT.md (the Director env table and MCP "How it works"). Resolve by keeping this PR's text; its citations are the same as #1092's.

Review round 1

How to verify

  • node --test tests/ (432 pass, 0 fail)
  • pre-commit run --files on every touched file
  • Every relative link and DEVELOPMENT.md#… anchor in touched files resolves
  • git grep finds no reference to a deleted file

— Claude Code agent, on @omesser's behalf.

🤖 Generated with Claude Code

@omesser omesser left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Soft-gate (Architect) — value preservation

Verdict: CLEARED with Softs
Tip verified: 02f3bb0a7301b4b7cc261d99fd108aa3b76ce2e0

Primary Hard axis (Oded): nothing of current import and value is lost. Docs compaction + ~10 MB asset delete. Checked DEVELOPMENT levers before→after vs base 6a496b1e; DESIGN/SPEC Capture/Windows/ADR-0024/0032 against code+ADRs; grepped deleted paths; compared cite edits to #1092.

Hard findings

None. No still-used command, env var, default, or procedure vanishes from DEVELOPMENT. DESIGN/SPEC Capture-drop, Windows-not-deferred, and ADR-0024/0032 alignment match living ADRs/code. Deleted docs/pr/, docs/pr-assets/, named docs/readme/*.png, and docs/research/naming-review-2026-09.md have zero living tree refs (permalinked PR bodies by SHA excluded as claimed). CONTEXT.md and docs/design/ untouched; research/ rest kept.

DEVELOPMENT levers (Hard 1)

  • Every FIDGET_* token from base still present; Trace Variables duplicate tables merged without dropping a row (FIDGET_TRACE_WINDOWS kept in the unified table).
  • Shell command set preserved (comment/whitespace only). Signing procedure kept under Keyring (scripts/dev-sign.sh + Keychain ACL).
  • Broken FIDGET_CAPTURABLE paragraph fixed to ADR-0024 semantics; reply-contract archived link now pins ignored test + pre-#135 README SHA.
  • MCP tool catalog deferred to README #harness--mcp (still lists speak / play_behavior / sensing / Memory + resources). Defaults (30s / 120 / 60 / 1024|8192 / gpt-4o-mini / data-folder paths) still stated.

DESIGN / SPEC (Hard 2)

  • Diagram Capture boxes gone; Sensing is titles/app under consent; Dropped section cites ADR-0031.
  • Windows no longer deferred (ships NSIS; stub/degraded cells remain). SPEC scope line: "Voice is deferred" only.
  • Screen-share story → Presence opt-out + ADR-0024; "Window titles deferred" removed; titles+app names under one consent (ADR-0032). Character count "two shipped" → "at least two styles" / eight ship in README — accurate.

Deleted paths (Hard 3)

git grep on tip: no hits for docs/pr/, docs/pr-assets/, naming-review, or deleted readme PNG basenames.

Overlap with #1092 (Hard 4)

ADR cite renumbers on shared DESIGN/SPEC lines match #1092 (0014→0020, drop "supersedes 0005", 0017→0022, non-loopback→0023). Compatible in spirit; DEVELOPMENT prose compaction will Soft-conflict with #1092's lighter cite-only edits (incl. Related-decisions section this PR drops — #1092's Soft (b) ADR-0010 residual is already ADR-0023 here).

Soft ledger

Item State
(a) CI on tip Met — checks ubuntu/mac/windows + Pages build green; deploy skipped
(b) Mergeable vs current main (ded07cf…) Open — mergeable_state: dirty. Real conflict only in docs/DEVELOPMENT.md Reply Contract Measurements (this tip's pinned SHA/ignored-test fix vs main's still-broken "archived lines 450–490" after #1087 rename). DESIGN/README auto-merge cleanly with #1087/#1089. Soft rebase keeping this tip's side
(c) Dirty vs #1092 (also dirty vs main) Open — both open and dirty; cite renumbers align, but DEVELOPMENT compaction vs #1092 cite-only + Related-decisions update will need a Soft rebase whichever lands second

Merge / draft

  • Draft: no
  • Mergeable: CONFLICTING / dirty vs current main (base-at-open 6a496b1e)
  • CI: green on tip

One-liner for Oded

Value preservation holds: every kept DEVELOPMENT lever and live DESIGN/SPEC constraint survives the compact+delete; Softs are a one-hunk rebase vs main and sequencing with #1092.

Babysit: none yet.

— Cursor agent (Architect), on @omesser's behalf.

omesser and others added 2 commits September 28, 2026 03:57
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omesser
omesser merged commit b855b89 into main Sep 28, 2026
6 checks passed

@omesser omesser left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Soft-gate (Architect) — value preservation (re-gate after tip push)

Verdict: CLEARED with Softs
Tip verified: 0f53d664a498655cefd3529fff8ef3ad6b56af98
Note: Already MERGED by @omesser at 2026-09-28 04:00:49 IDT as b855b898… (main tip now 72028496… via later #1102). This re-gate is historical Soft-ledger update on the tip that landed.

Primary Hard axis (Oded): nothing of current import and value is lost. Re-verified on new tip after rebase + "docs: Address review round 1" vs PR base 694d9f99…. Round-1 restores and sibling overlap with open #1092 checked.

Hard findings

None. DEVELOPMENT levers (every base FIDGET_*, commands, signing/keyring, defaults 30s/120/60/1024|8192/gpt-4o-mini/data-folder, MCP catalog → README #harness--mcp) preserved. DESIGN/SPEC Capture-drop (ADR-0031), Windows-not-deferred, ADR-0024/0032 consent stories accurate; stale "two shipped Characters" gone (now "at least two styles"). Deleted docs/pr/, docs/pr-assets/, and six docs/readme/*.png have zero living-tree refs. docs/research/naming-review-2026-09.md restored with shipped preamble. Round-1: domain.md proceed-silently restored; DND/Sound under Settings; verify-overlay.sh → docs/DEVELOPMENT.md; #594 image pinned to 3d16d6fc.

DEVELOPMENT levers (Hard 1)

  • Tip vs base: no FIDGET_* token lost (FIDGET_BENCH_* still named via reply-contract ignored-test note). Trace / Completer / Harness / MCP vars and defaults still stated.
  • Shell command set + scripts/dev-sign.sh Keychain ACL procedure kept. MCP tool list defers to README #harness--mcp (live speak / play_behavior / sensing / Memory catalog).

DESIGN / SPEC (Hard 2)

  • Capture tiers dropped with ADR-0031 cites; screen-share = capturable-by-default + Presence opt-out (ADR-0024); titles+app names under one consent (ADR-0032).
  • Windows ships (NSIS); no "Windows deferred". Character copy is style-span, not "two shipped".

Deleted paths + Round-1 restores (Hard 3 / 5)

  • git grep on tip: no docs/pr/, docs/pr-assets/, or deleted readme PNG basenames.
  • naming-review present + "Shipped: … #1079" preamble; domain proceed-silently present; verify-overlay checklist lines name docs/DEVELOPMENT.md.

Overlap with #1092 (Hard 4)

ADR numbers on tip match living ADRs; no incompatible renumber vs #1092 tip 268aba23…. #1092 remains OPEN / CONFLICTING / DIRTY vs post-merge main — expected Soft DEVELOPMENT conflict (Director env table + MCP "How it works"); resolve keeping this PR's compacted text (citations already aligned). Cite-compat Soft; sequencing Soft remains.

Soft ledger

Item State
(a) CI on tip Met — checks ubuntu/macos/windows SUCCESS; Pages build SUCCESS; deploy SKIPPED (OK) on run 36364263977 / 36364263990
(b) Mergeable vs current main Met — tip rebased onto main after #1085/#1087/#1089; merged cleanly as b855b898… (prior Soft dirty Reply-Contract hunk cleared by rebase)
(c) Sequencing / dirty vs open #1092 Open — #1092 tip 268aba23… still CONFLICTING/DIRTY vs main that now includes this PR; ADR cites compatible; DEVELOPMENT Soft-conflict remains for whoever rebases #1092

Merge / draft

  • Draft: no
  • Mergeable: already MERGED (was MERGEABLE/UNSTABLE while CI settled)
  • CI: green on tip

One-liner for Oded

Value preservation still holds on 0f53d664… after round-1 restores; Soft (b) cleared by the rebase and the PR is already merged — only Soft left is #1092 rebasing onto post-#1093 main.

Babysit: stop (merged). Hand #1092 Soft rebase to Coder if desired.

— Cursor agent (Architect), on @omesser's behalf.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant