chore: consolidate neotoma-inspector into neotoma (subtree import)

[castor-agent]

Summary

Consolidates the standalone neotoma-inspector GitHub repo into neotoma as a regular subdirectory under inspector/, preserving full commit history via git subtree. Tracked as plan entity ent_96dbd62a85216fe0bbf76276.

Why

The Inspector is no longer a third-party tool that talks to Neotoma — it's the product UI, served by the same binary, on the same URLs (after PR #323's content-negotiation unification), sharing the same canonical data. The submodule split implies more separation than actually exists. Every cross-boundary change requires two coordinated PRs (e.g. PR #323 needed inspector commit 48b9d42 + parent commit 7fb9ada4e). Consolidating removes that friction.

What's in the PR

Three commits:

1. chore: deregister inspector submodule (prep for subtree consolidation)

   • Removes the [submodule "inspector"] entry from .gitmodules.
   • Removes the inspector submodule registration.

2. Add 'inspector/' from commit 'a4dc87bd4ad33b535bce3d5dbdd06a9cba0f92c2' (auto-generated by git subtree add)

   • Imports the inspector's origin/main HEAD as a real subtree under inspector/.
   • Every previous inspector commit is reachable from HEAD (e.g. git log -- inspector/ shows c50ada70c, 33c0840f9, 1f3c48713, etc. as real commits in this repo's history).
   • No history loss: --squash was NOT used.

3. chore: update docs + build script after inspector consolidation

   • scripts/build_inspector.js: error message no longer suggests git submodule update --init inspector.
   • docs/plans/neotoma-harness-plan.md, docs/plans/neotoma-harness-landing-page-net-plan.md: parenthetical refers to inspector/ in this repo with an archive note.
   • docs/testing/ROUTE_COVERAGE_MATRIX.md, docs/testing/WHY_PARTIAL_ROUTE_COVERAGE.md: 2026-04-15 notes updated.
   • frontend/src/components/illustrations/InspectorPreviewIllustration.tsx: external CTA URL points at the inspector directory in this repo.

Test plan

• Verified inspector commit history is preserved (git log --oneline -- inspector/ | head -20 shows real inspector commits, not just the merge).
• Verified inspector/.git does NOT exist (would indicate residual submodule registration).
• npm install && node scripts/build_inspector.js produces dist/inspector/index.html.
• npx tsc --noEmit clean.
• 33/33 tests/integration/inspector_bundled_mount.test.ts pass.

What's NOT in this PR

• PR Mode taxonomy + inspector bundling + content-negotiation unification #323 (mode taxonomy + content-negotiation unification) was authored before this consolidation; it depends on inspector commit 48b9d42 via the old submodule pointer. The two PRs should be merged in order: Mode taxonomy + inspector bundling + content-negotiation unification #323 first (so the inspector changes there are anchored to the submodule history), then this consolidation (which brings everything else in). Alternative ordering works too but produces a different SHA for the final tree.
• Archiving the standalone neotoma-inspector repo on GitHub. That's a manual step after this PR lands:
  1. Update markmhendrickson/neotoma-inspector README to point here.
  2. Close standalone repo's open PR Feature unit FU-110 completion #1 (already stale per pre-flight audit).
  3. Archive the repo via GitHub Settings → Archive.

What stays as submodules

foundation, mcp/web-scraper, writ, frontend/src/shared, docs/private. They have genuine independent existence (foundation is shared across repos; web-scraper is published as an MCP server independently; writ is a separate project).

Reviewer focus

• Spot-check that an inspector commit (e.g. a4dc87bd4) is reachable from this branch's HEAD.
• Spot-check that inspector/ is a normal directory (no .git, no symlink).
• Verify the build pipeline still produces a working dist/inspector/.
• Verify nothing important still references the standalone repo URL.

🤖 Generated with Claude Code

[castor-agent]

@claude review

[github-actions]

Claude finished @castor-agent's task —— View job

---

Claude PR Review

Reviewed against docs/developer/pr_review_reading_list.md (always-read invariants + conditional docs for touched paths).

Scope sanity-check. Setting aside the ~38k-line subtree import, the substantive diff is tiny and well-contained: .gitmodules (−3), scripts/build_inspector.js (±5), frontend/.../InspectorPreviewIllustration.tsx (±8), four docs (±10). No src/, no openapi.yaml, no tests/contract/, no auth surface, no error envelope. Therefore the cross-cutting guardrails in docs/architecture/change_guardrails_rules.mdc (idempotency keys, openapi-first, proxy trust, manifest, breaking changes) are not in scope here. Subtree-imported inspector/ code was authored under the standalone repo's own controls and is being moved, not modified — this is correctly out of scope for invariant checks.

History preservation confirmed: git log -- inspector/ shows real inspector commits, no inspector/.git, no submodule pointer left over.

Blocking

1. CI workflow still references the deleted submodule. .github/workflows/ci_test_lanes.yml:34-35 runs git submodule update --init --depth 1 inspector. After this PR, there is no inspector entry in .gitmodules, so the command will exit non-zero ("No submodule mapping found in .gitmodules for path 'inspector'") and break the ci_test_lanes job on every PR. This step needs to be removed in the same PR. Note your bot can't edit .github/workflows/, so a human committer must land that change — but the PR should not be merged before the workflow is fixed, or main CI will go red on the merge commit.

Non-blocking (should fix in this PR or a follow-up)

2. Stale "submodule" wording in production code. src/services/inspector_mount.ts:46,53,54 — JSDoc and an internal variable name (submoduleDistDir) still talk about "the submodule". Behavior is unchanged (path is inspector/dist either way), so this is a comment/symbol drift, not a logic bug. Worth renaming for accuracy.

3. Stale wording in scripts/build_inspector.js:4. Top-of-file docstring still says "Build the Inspector submodule…". The error message in the same file was updated (commit 5588ce6cb), but the docstring wasn't.

4. Stale references in non-historical docs:

   • docs/coverage_manifest.md:179,181,261 — describes inspector/ as "git submodule" / "external submodule".
   • docs/subsystems/plans.md:84 — "A separate PR against the inspector submodule will…".
   • docs/developer/scripts_reference.md:75 — "packages the inspector submodule for distribution".
   • inspector/README.md:121 — "git submodule add … inspector" instructions (this is the inspector's own README; arguably out of scope of the move, but it now lives in this repo and is reachable). Consider patching to reflect the new layout.

   Historical release supplements under docs/releases/in_progress/v0.4.1, v0.6.0, v0.7.0, v0.12.0, v0.12.1 etc. are fine to leave alone — supplement immutability rule (change_guardrails_rules.mdc MUST Feature unit FU-110 testing #7).

5. inspector/package.json still names the package neotoma-inspector. Not a defect per se — it just means the published name (if Inspector were ever published independently) is still neotoma-inspector. Likely intentional but worth a conscious choice given the consolidation narrative.

Things I verified and is fine

• No openapi.yaml / src/shared/contract* / handler / contract-test changes → no openapi-first or idempotency_key obligations triggered (change_guardrails_rules.mdc MUST Feature unit FU-110 completion #1, Feature unit FU-112 execution #11).
• No new Express routes / auth middleware / LOCAL_DEV_USER_ID / req.socket.remoteAddress / X-Forwarded-For touched → no protected_routes_manifest.json regeneration needed; threat-model surface unchanged.
• No PII risk introduced (no logging/metrics/event changes).
• Determinism: not affected (no reducer / store / event logic touched).
• InspectorPreviewIllustration.tsx URL change is purely a marketing link redirect; analytics sendCtaClick call unchanged.
• Scope creep: none — diff outside the subtree is exclusively rename-aware reference updates.

Release-supplement implications

A consolidation like this is normally worth a one-liner in the next supplement's notes (developer-facing: "Inspector source consolidated into the main repo; submodule no longer required"). Not a "Breaking changes" entry since no published API / CLI / MCP surface tightens — just a heads-up for anyone with stale git submodule update --init muscle memory.

Summary

The subtree mechanics look clean and history is preserved. The blocking issue is CI: removing .gitmodules's inspector entry without removing the matching ci_test_lanes.yml step will break CI on merge. Everything else is cosmetic / drift.

• Read docs/developer/pr_review_reading_list.md
• Read always-read invariants (change_guardrails_rules.mdc)
• Scoped diff outside the subtree; confirmed no src/, openapi.yaml, tests/contract/, or auth-surface changes (no further conditional docs triggered)
• Reviewed PR against constraints
• Posted review
  · Branch: claude/consolidate-inspector

[castor-agent]

/create_pr skill audit

Automated audit against the /create_pr skill (Neotoma plan ent_8cde942847555a83253dfe5b), which defines the standard PR description structure (Problems / Solutions / UX improvements / Documentation / Test plan / Breaking changes), the pre-PR checklist from .claude/rules/change_guardrails_rules.md, and the functional-change documentation gate (docs entry + docs/site/site_doc_manifest.yaml + docs server surfacing).

Verdict: does not fully meet standards. Gaps below; recommended changes follow each item.

Findings

• Missing required sections: Problems, Solutions, UX improvements, Documentation, Breaking changes.
• Breaking changes section MUST be present, even for non-breaking PRs (write No breaking changes.).
• No Related section and no Fixes #N / Closes #N reference — link the plan and/or issue(s) so the PR closes them on merge.

Recommended changes

Update the PR description to match the skill template exactly:

## Problems
- <Concrete pain point or gap.>

## Solutions
- <Concrete change made.>

## UX improvements
- <User-visible behavior change, or `No user-visible change.`>

## Documentation
- <docs/... path(s) added or updated; parameters/outputs/examples/error modes covered.>
- <`docs/site/site_doc_manifest.yaml` entry added/updated; docs service tests pass.>
- <Or: `No functional change; no user-facing docs required.`>

## Test plan
- [ ] `npm run type-check`
- [ ] `npm test`
- [ ] `npm test -- src/services/docs` (if docs changed)
- [ ] Manual verification: <steps>

## Breaking changes
No breaking changes.

## Related
- Plan: <Neotoma plan entity_id or docs/ path>
- Issue(s): <#N>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Posted by /create_pr skill audit run. See .claude/skills/create_pr/SKILL.md for the full template.