Brings in main's fix(workspace) #185, fix(launch) #184, and a large
documentation roadmap addition (#183 + several smaller PRs covering
codebase readability, project structure gates, etc.).

Adds the `isolation` field to MountConfig literals introduced by main
in test fixtures inside `src/app/context.rs` and `src/workspace/resolve.rs`
(2 + 3 sites, all `MountIsolation::Shared` since they're not testing
isolation behavior). These literals predate this branch's
`isolation`-field addition; main couldn't anticipate the new required
field, so the merge picks them up unmodified and we backfill the field
here.

No conflicts in the merge itself.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…183)

* docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec

Primary goal shift: codebase must be verifiable for AI-generated code.

- §0: replace generic description with explicit verifiability rationale
  (module contracts, localised concerns, types/behaviour separation)
- §4 intro: add "Why structure matters for AI-generated code" section with
  audit-units table mapping each post-split file to one reviewable question
- §4 4a: expand config/types.rs from description to full execution spec —
  exact type list, post-split mod.rs content, zero-change submodule
  guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T
  which resolves through mod.rs re-exports unchanged), impl-extension
  pattern already in use documented

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 14 — editor method map, app helpers, //! queue

- §4 4c: config/editor.rs split is now execution-ready — complete
  6-file method-to-file table with private helper placement verified
  (validate_candidate→io.rs, table_path_mut→mod.rs pub(super),
  auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig)
- §4 4e: app/mod.rs split complete — all private helpers mapped
  (parse_auth_forward_mode_from_cli→config_cmd.rs,
  workspace_env_scope→workspace_cmd.rs, print_env_table note,
  remove_data_dir_if_exists→dispatch.rs)
- §10 step 5: add //! priority queue — 10 files with draft content,
  prioritised by cold-landing impact and AI audit risk; selector.rs
  and instance/mod.rs explicitly document the /→__ invariant

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed

- §4 4d: correct operator_env dependency graph — layers.rs imports
  both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable
  resolve_operator_env wrapper at line 797); still a valid DAG
- §4 4f: verify trust.rs split safety — FnOnce injection pattern means
  launch_pipeline.rs has zero dependency on trust.rs; import chain
  documented; trust bypass audit now requires reading only ~60L
- §9 OQ1 closed: op_cache.rs read in full — 4-level structure,
  per-level invalidation, no TTL/expiry (expiry handled at OpCli
  subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence

- Fix duplicate Rule 3 section introduced by previous edit; add docker.rs
  co-location note as third edge case (three edge cases, not two)
- Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171
  (was listed as 782L); propose 6-file tab-by-tab split with auditability
  note on the security-adjacent Secrets tab
- Add §10 execution-order note: 4a and 4c are independent — editor.rs
  imports AppConfig via crate::config re-exports regardless of 4a order
- Append iteration 16 log entry with confidence table and weakest sections

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections

- Add instance/auth.rs to //! priority queue at #4: four security
  invariants (0o600 perms, symlink rejection, TOCTOU-safe writes,
  macOS Keychain) documented in draft //! content
- Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types
  mixed with impl blocks; propose 5-file types/behavior split
- Correct stale line counts: render/list.rs 1122→1989 (PR #171 added
  render_environments_subpanel); state.rs 865→992; priorities upgraded
- Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332,
  mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944
- Renumber //! priority queue to 11 entries (was 10)

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal

- Close OQ2: agent_allow.rs read in full — 55L, correct //! doc,
  design sound; serves as model for //! priority queue pattern
- Add render/list.rs as new Rule 5 violator: 668L production (PR #171
  added render_environments_subpanel); propose 3-file split (mod.rs,
  details.rs, subpanels.rs); note import-path change for agents_block_agent_count
- Update §1 module map: agent_allow.rs entry corrected with size/API

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal

- Correct input/editor.rs: 2349L total (was 1304L), 1141L production
  (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn
  handle_editor_modal at line 618 was invisible to previous grep pattern;
  now the largest production file in the codebase; priority → Critical
- Correct input/save.rs: 1472L total, 661L production (was 567L)
- Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers),
  secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs
- Update key insight paragraph naming input/editor.rs as largest production file

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict

- Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority
  order; rename existing 4f (launch.rs) → 4g; add circular-import risk note
  for ManagerStage/EditorState split sequencing
- Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid
  is a tightly-coupled rendering loop); section comments compensate for missing //!
- Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs;
  within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable)

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections

- Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file
  split (mod.rs + flow.rs + preview.rs); no cross-dependency between
  flow and preview groups; §10 4f-v updated from Optional to concrete plan
- Fix //! queue preamble: "first 10 files" → "first 11 files"
- Correct save.rs module map (1418→1472L, correct key exports) and
  hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save
  is the Phase 2 partner at ~149L)

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis

- Analyze input/list.rs: 214L production (tests at 215); has //! doc;
  two focused pub(super) fns; no split needed; Low priority; correct module map
- Add mount_info.rs to hot-spot table: 277L production; Low priority;
  has //! doc; correct module map with 3 public enums + inspect fn
- Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected

- Expand audit units table from 8 to 13 entries: add state/types.rs,
  state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs,
  input/save/preview.rs — all targeting PR #171 AI-generated console code
- Add PR #171 context note linking 5 new entries to AI-generated code concern
- Correct input/mod.rs module map: 369L, add InputOutcome enum to exports
- Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed

- Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded
  1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element
  (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted
- Correct render/mod.rs module map: 421L; FooterItem + palette constants
  + render_header + centered_rect_fixed added to key exports
- Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum)
  vs "Secrets / Environments" (UI label); /stub qualifier already removed

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat

- Correct too_many_lines count: 13 across 8 → 16 across 11 files
  (PR #171 added 5 suppressions in console/manager); add full breakdown
  table; update all 3 occurrences in roadmap
- Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow)
- Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed

- Add console/mod.rs to hot-spot table: 406L/307L production (Low);
  correct module map from ~200 → 406L; note missing //! doc with
  ConsoleStage design block comment worth promoting
- Add op_picker/render.rs to hot-spot table: 865L/545L production
  (Medium); PR #171 AI-generated; 14 functions in two logical groups
  (entry/helpers vs level renderers); split into levels.rs proposed
- Correct 3 stale ~200L estimates for console/mod.rs across roadmap

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction

- Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High);
  PR #171 AI-generated; OpPickerState types+behavior split opportunity;
  has 7-line //! doc; module map split into two rows (mod.rs + render.rs)
- Add op_picker/render.rs 2-file split proposal: render.rs (coordinator)
  + render_pane.rs (pane/level renderers); no cross-dependency confirmed
- Correct operator_env.rs total: 1569→2130L (880L production); update
  4 occurrences across hot-spot table, ASCII tree, §4 analysis

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections

- Add op_picker/mod.rs formal 3-file split: loading.rs (async load family
  ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors)
- Correct "24 files" → "28+" for 500L threshold count
- Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note)

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis

- §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs
  → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs →
  render.rs + pane.rs); document impl-extension and import-path caveats
- §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files
  have //! docs, no file exceeds ~350L production; classified as exemplar
  (not a split candidate); document git_prompt.rs coupling-density
  justification and input.rs as 28-file false positive (144L production)
- §1 module map: expand single file_browser/ row to 5 individual rows
  with production LOC and dominant concern per file

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections

- §4: Add "Alternative thesis: documentation-first verification" — challenges
  the two core assumptions behind file splitting (files-as-audit-unit and
  file-size-as-context-constraint); adds 7-criterion comparison table vs
  structure-first approach; introduces phased combined recommendation:
  Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs,
  zero structural change); Phase 2 = splits only for >600L production files
  (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K
- Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and
  8 locations respectively; verified by fresh find|xargs wc -l scan)
- §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L),
  source_picker.rs (244L) — all PR #171 additions with //! docs

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 31 — fix 600L→800L threshold error, correct LOC

- §4 alternative thesis: correct ">600L production → 4 files" claim
  introduced in iteration 30; re-verified all 9 candidate files via
  #[cfg(test)] line position; threshold must be >800L to get exactly 4
  files (9 exceed 600L); add verification table with test-start lines
- Production LOC corrections (5+ locations each):
  launch.rs 1085→~1077, operator_env.rs 810→~880,
  app/mod.rs 928→~957, config/editor.rs 503→~584
- §2 OpPicker row: replace vague "no entry yet" with confirmed gap:
  PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10
  named); omits op_picker/, agent_picker.rs, scope_picker.rs,
  source_picker.rs and pre-dates the manager/ sub-structure split

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 32 — two-tier spec arch, behavioral spec template

- §8.1: Add two-tier spec architecture table distinguishing feature specs
  (public Starlight MDX, user-facing) from behavioral specs (internal
  docs/internal/specs/, for AI code verification) — resolves contradiction
  between §4 (which said docs/internal/specs/) and §8.1 (which said
  "no longer needed; specs are public")
- §8.1: Add concrete behavioral spec template for op_picker/ with state
  machine table and 3 INV invariant entries each with a grep-executable
  "Verify by:" command; template directly usable for the 3 Phase 1 specs
- §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim
- Confirmed render/editor.rs ~736L and render/list.rs ~668L production
  (no interspersed production code — all test blocks follow consecutively)

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 33 — executive summary, §0 correctness

- §0: Add executive summary (~300 words) with core problem, 3-phase
  recommendation, key counter-argument, and navigation table pointing
  to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a
  readability roadmap with no entry-point orientation
- §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs
  current verified size; stale reference was in the first section readers see)
- §0 item 3: Add "(selective)" qualifier and explicit note that standard
  Rust co-locates struct+impl — impl-extension pattern is justified only
  for files >800L production, not as a universal rule

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 34 — spec priority reorder, §10 Phase 1 track

- §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //!
  doc, ~1077L production, critical path — all jackin load failures trace
  here); drop config/editor.rs from Phase 1 (its 963L test suite already
  serves as behavioral spec — tests are behavioral examples); reduce Phase
  1 from 3 specs to 2 specs; add reasoning for the priority ordering
- §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling
  setup) + Track B (Phase 1 behavioral spec authoring); Track B includes
  specific INV invariants to capture for runtime/launch.rs grounded in
  reading the actual function structure (step comment positions); adds
  sequencing rationale: spec must precede structural splits

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 35 — verified INV entries for runtime/launch.rs

Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from
iteration 34 (inferred from step comment positions) with 5 verified INVs
citing exact line numbers:
- INV-1: trust gate (line 594) precedes image build (line 736)
- INV-2: container name claimed (line 754) between image build and network
- INV-3: token verified (line 763) before network creation (line 827)
- INV-4: render_exit called at lines 886 AND 890 (all exit paths)
- INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup,
  crash→disarm (explains jackin hardline compatibility)
Corrected wrong line number: claim_container_name call is at 754, not 918
(918 is the function definition). Each INV has a grep-executable Verify by.

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 36 — CI gate for PROJECT_STRUCTURE.md freshness

§3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
three concrete options:
- Option A: CONTRIBUTING.md rule (necessary but insufficient)
- Option B: ci.yml git-diff-scoped shell check (recommended) — only checks
  files added in the current PR so it doesn't require fixing existing stale
  entries before merging; greps for module directory name in prose
- Option C: Structured TOML module registry (over-engineered for scale)
Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts
pattern already established in docs/scripts/

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iterations 36-37 — CI gate + greenfield workspace architecture

Iteration 36:
- §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
  3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry);
  recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded
  in existing check:repo-links.ts pattern from docs/scripts/

Iteration 37 (operator directive: greenfield Rust structure):
- §4: Add "Greenfield architecture — ideal structure for a growing project"
  section based on verified cross-module dependency graph (grep iteration 37)
- Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0;
  config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3
- Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace
  types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config)
- Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui,
  jackin-runtime, jackin-console, jackin-shell + thin binary
- Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary
- Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 38 — Rust workspace standards, community evidence

Ground workspace recommendation in real-world project research:
- ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers
- starship and fd-find stay single-crate at 1M+ LOC — no library use case
- jackin (43K LOC, no external consumers) maps to starship/fd pattern
  → single-crate is community-standard; "stay single-crate" recommendation confirmed

Update greenfield workspace structure to follow matklad's pattern:
- Virtual manifest at root (no [package] in root Cargo.toml)
- Flat crates/ directory (not nested); crate names match folder names
- version = "0.0.0" for unpublished internal crates
- Add inline dep comments to each crate in the ASCII structure

Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings +
Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22)

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): revise §7.9 + §3 — adopt per-directory README.md

§7.9: Reverse previous "reject" recommendation to "adopt" per-directory
README.md for major src/ module directories. Rationale: README.md is
AI-native — Claude Code, Copilot, Cursor load it automatically on directory
entry, giving AI agents orientation before they decide which file to open.
PROJECT_STRUCTURE.md being confirmed stale removes the main argument for
the "single root file" approach.

Add three-layer documentation model table:
- README.md: directory orientation (AI + human, on entry)
- AGENTS.md: agent workflow rules (root, session start)
- CLAUDE.md: @AGENTS.md pointer only — NEVER add content here
- //! docs: file-level contracts (when reading/editing)

Add specific README.md content targets for 7 directories
(src/, src/runtime/, src/console/, src/console/manager/,
src/console/widgets/, docs/, docs/internal/).

§3 target document shape: Add per-directory README.md to proposed
hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md
design principle (single-line @AGENTS.md — never duplicate content).

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): internal docs are browsable — unified Starlight site

Operator directive: internal docs (architecture, specs, ADRs, roadmap) should
be browsable, not hidden filesystem files. They are a different TYPE of docs
focused on implementation details and vision, published as a "Developer
Reference" section of the Starlight site.

§3 target document shape:
- docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages)
- Browsable at jackin.tailrocks.com/internal/
- Sidebar: "Developer Reference" group (collapsed by default) with sub-sections
  for architecture, code-tour, contributing, testing, decisions, specs, roadmap
- Include astro.config.ts sidebar config snippet

§8.1 two-tier spec distinction eliminated:
- Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/
- Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location
- Both browsable and searchable via Starlight; AI agents can be pointed to URLs

§8.3 + §4:
- All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/
- ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable)
- README.md pointer for src/runtime/ updated to URL reference

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): §11 — modern Rust docs platform (future project)

Add §11 capturing the vision for a modern docs.rs alternative with:
- rustdoc JSON ingestion → Astro Starlight presentation
- MCP server for AI agent queries (Context7 alternative for Rust)
- Rust-specific query types: rust_get_context(), rust_find_impls(),
  rust_search_types() — things Context7 cannot provide
- Comparison table vs Context7
- Architecture diagram (ingestion → processing → Starlight + MCP)
- Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs
- Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional
  prototype for the platform's processing and presentation layers

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 39 — update §0, fix stale internal/ paths

§0 executive summary: rewrite to reflect decisions from iterations 30-38:
- browsable internal docs (jackin.tailrocks.com/internal/)
- per-directory README.md adoption (§7.9 reversed)
- CLAUDE.md = @AGENTS.md single-line pointer only
- greenfield workspace architecture (matklad's virtual manifest pattern)
- §11 future project: modern Rust docs platform / Context7-for-Rust
- document size 1800+ → 2200+

Fix stale docs/internal/ bare paths not caught by iteration 38 sweep:
- Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths
- §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path
- §10 Track B item 2: op-picker spec path → Starlight MDX

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 40 — §7.15 pipeline + Rule 4 pub audit

§7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline
- Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended)
  / rustdoc-json crate as Rust binary
- Option B recommended: matches existing docs/scripts/ pattern, nightly
  isolated to separate CI step, zero effect on stable build
- Key design: URL at /internal/api/, cross-links to behavioral specs,
  Starlight unified search, prototype for §11 future project
- Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit
- Recommend: adopt after Phase 1 //! sprint (value ∝ coverage)

§4 Rule 4 pub discipline: replace estimated "50-100 items" guess with
verified numbers from iteration 40 grep:
- 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files
- 0 uses of unreachable_pub lint — no enforcement gate
- Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8)
- Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn"
- Revised scope: ~150-200 mechanical conversions (excludes entry points)

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): split research into 19 actionable items

Delete _research_notes.md (no longer needed).

Replace 2343L READABILITY_AND_MODERNIZATION.md with:
- README.md: index of all 19 items with phase, ordering notes, links
- READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L)
- items/ITEM-001 through ITEM-019: individual actionable items

Items by phase:
  Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011
  Phase 1 (needs confirmation): ITEM-005, 016, 018
  Phase 2 (structural splits, confirmation required): ITEM-012..015
  Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace)

Each item has: summary, key files with line numbers, steps, what
needs confirmation, and relevant research backing from the 40-iteration
analysis loop.

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): migrate 19 items to Starlight reference/roadmap section

Move all codebase health roadmap items from docs/internal/roadmap/items/
(plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/
(MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/).

Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to
astro.config.ts. Deletes the old items/ directory. Updates the internal
README to redirect to the new location.

Also adds codebase-readability.mdx — a new overview item that captures
the overall readability/restructuring program with a recommended execution
order: file splits first, then greenfield workspace, then per-directory
README+AGENTS.md, then docs and specs.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): remove premature internal/roadmap/README.md

The internal/ structure doesn't exist yet — it will be created as part
of the roadmap items themselves. No need for a redirect stub now.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive

All content has been distilled into the individual Starlight roadmap pages.
The full 2343L research is preserved in git history at commit b7e9fc2.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): fix check:repo-links errors + remove iteration log

- Replace plain code spans with <RepoFile> for validate.rs, mise.toml,
  Cargo.toml, and op_picker/mod.rs
- Remove deleted READABILITY_AND_MODERNIZATION.md reference from
  codebase-readability.mdx
- Delete _iteration_log.md (git history is the archive)

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): fix lychee false-positive link in move-contributing-testing

The example redirect text contained a markdown hyperlink to a proposed
future file path that doesn't exist yet. Changed to a code span.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

---------

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>
Co-authored-by: Claude <noreply@anthropic.com>

…183)

* docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec

Primary goal shift: codebase must be verifiable for AI-generated code.

- §0: replace generic description with explicit verifiability rationale
  (module contracts, localised concerns, types/behaviour separation)
- §4 intro: add "Why structure matters for AI-generated code" section with
  audit-units table mapping each post-split file to one reviewable question
- §4 4a: expand config/types.rs from description to full execution spec —
  exact type list, post-split mod.rs content, zero-change submodule
  guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T
  which resolves through mod.rs re-exports unchanged), impl-extension
  pattern already in use documented

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 14 — editor method map, app helpers, //! queue

- §4 4c: config/editor.rs split is now execution-ready — complete
  6-file method-to-file table with private helper placement verified
  (validate_candidate→io.rs, table_path_mut→mod.rs pub(super),
  auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig)
- §4 4e: app/mod.rs split complete — all private helpers mapped
  (parse_auth_forward_mode_from_cli→config_cmd.rs,
  workspace_env_scope→workspace_cmd.rs, print_env_table note,
  remove_data_dir_if_exists→dispatch.rs)
- §10 step 5: add //! priority queue — 10 files with draft content,
  prioritised by cold-landing impact and AI audit risk; selector.rs
  and instance/mod.rs explicitly document the /→__ invariant

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed

- §4 4d: correct operator_env dependency graph — layers.rs imports
  both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable
  resolve_operator_env wrapper at line 797); still a valid DAG
- §4 4f: verify trust.rs split safety — FnOnce injection pattern means
  launch_pipeline.rs has zero dependency on trust.rs; import chain
  documented; trust bypass audit now requires reading only ~60L
- §9 OQ1 closed: op_cache.rs read in full — 4-level structure,
  per-level invalidation, no TTL/expiry (expiry handled at OpCli
  subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence

- Fix duplicate Rule 3 section introduced by previous edit; add docker.rs
  co-location note as third edge case (three edge cases, not two)
- Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171
  (was listed as 782L); propose 6-file tab-by-tab split with auditability
  note on the security-adjacent Secrets tab
- Add §10 execution-order note: 4a and 4c are independent — editor.rs
  imports AppConfig via crate::config re-exports regardless of 4a order
- Append iteration 16 log entry with confidence table and weakest sections

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections

- Add instance/auth.rs to //! priority queue at #4: four security
  invariants (0o600 perms, symlink rejection, TOCTOU-safe writes,
  macOS Keychain) documented in draft //! content
- Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types
  mixed with impl blocks; propose 5-file types/behavior split
- Correct stale line counts: render/list.rs 1122→1989 (PR #171 added
  render_environments_subpanel); state.rs 865→992; priorities upgraded
- Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332,
  mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944
- Renumber //! priority queue to 11 entries (was 10)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal

- Close OQ2: agent_allow.rs read in full — 55L, correct //! doc,
  design sound; serves as model for //! priority queue pattern
- Add render/list.rs as new Rule 5 violator: 668L production (PR #171
  added render_environments_subpanel); propose 3-file split (mod.rs,
  details.rs, subpanels.rs); note import-path change for agents_block_agent_count
- Update §1 module map: agent_allow.rs entry corrected with size/API

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal

- Correct input/editor.rs: 2349L total (was 1304L), 1141L production
  (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn
  handle_editor_modal at line 618 was invisible to previous grep pattern;
  now the largest production file in the codebase; priority → Critical
- Correct input/save.rs: 1472L total, 661L production (was 567L)
- Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers),
  secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs
- Update key insight paragraph naming input/editor.rs as largest production file

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict

- Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority
  order; rename existing 4f (launch.rs) → 4g; add circular-import risk note
  for ManagerStage/EditorState split sequencing
- Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid
  is a tightly-coupled rendering loop); section comments compensate for missing //!
- Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs;
  within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections

- Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file
  split (mod.rs + flow.rs + preview.rs); no cross-dependency between
  flow and preview groups; §10 4f-v updated from Optional to concrete plan
- Fix //! queue preamble: "first 10 files" → "first 11 files"
- Correct save.rs module map (1418→1472L, correct key exports) and
  hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save
  is the Phase 2 partner at ~149L)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis

- Analyze input/list.rs: 214L production (tests at 215); has //! doc;
  two focused pub(super) fns; no split needed; Low priority; correct module map
- Add mount_info.rs to hot-spot table: 277L production; Low priority;
  has //! doc; correct module map with 3 public enums + inspect fn
- Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected

- Expand audit units table from 8 to 13 entries: add state/types.rs,
  state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs,
  input/save/preview.rs — all targeting PR #171 AI-generated console code
- Add PR #171 context note linking 5 new entries to AI-generated code concern
- Correct input/mod.rs module map: 369L, add InputOutcome enum to exports
- Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed

- Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded
  1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element
  (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted
- Correct render/mod.rs module map: 421L; FooterItem + palette constants
  + render_header + centered_rect_fixed added to key exports
- Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum)
  vs "Secrets / Environments" (UI label); /stub qualifier already removed

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat

- Correct too_many_lines count: 13 across 8 → 16 across 11 files
  (PR #171 added 5 suppressions in console/manager); add full breakdown
  table; update all 3 occurrences in roadmap
- Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow)
- Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed

- Add console/mod.rs to hot-spot table: 406L/307L production (Low);
  correct module map from ~200 → 406L; note missing //! doc with
  ConsoleStage design block comment worth promoting
- Add op_picker/render.rs to hot-spot table: 865L/545L production
  (Medium); PR #171 AI-generated; 14 functions in two logical groups
  (entry/helpers vs level renderers); split into levels.rs proposed
- Correct 3 stale ~200L estimates for console/mod.rs across roadmap

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction

- Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High);
  PR #171 AI-generated; OpPickerState types+behavior split opportunity;
  has 7-line //! doc; module map split into two rows (mod.rs + render.rs)
- Add op_picker/render.rs 2-file split proposal: render.rs (coordinator)
  + render_pane.rs (pane/level renderers); no cross-dependency confirmed
- Correct operator_env.rs total: 1569→2130L (880L production); update
  4 occurrences across hot-spot table, ASCII tree, §4 analysis

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections

- Add op_picker/mod.rs formal 3-file split: loading.rs (async load family
  ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors)
- Correct "24 files" → "28+" for 500L threshold count
- Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis

- §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs
  → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs →
  render.rs + pane.rs); document impl-extension and import-path caveats
- §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files
  have //! docs, no file exceeds ~350L production; classified as exemplar
  (not a split candidate); document git_prompt.rs coupling-density
  justification and input.rs as 28-file false positive (144L production)
- §1 module map: expand single file_browser/ row to 5 individual rows
  with production LOC and dominant concern per file

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections

- §4: Add "Alternative thesis: documentation-first verification" — challenges
  the two core assumptions behind file splitting (files-as-audit-unit and
  file-size-as-context-constraint); adds 7-criterion comparison table vs
  structure-first approach; introduces phased combined recommendation:
  Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs,
  zero structural change); Phase 2 = splits only for >600L production files
  (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K
- Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and
  8 locations respectively; verified by fresh find|xargs wc -l scan)
- §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L),
  source_picker.rs (244L) — all PR #171 additions with //! docs

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 31 — fix 600L→800L threshold error, correct LOC

- §4 alternative thesis: correct ">600L production → 4 files" claim
  introduced in iteration 30; re-verified all 9 candidate files via
  #[cfg(test)] line position; threshold must be >800L to get exactly 4
  files (9 exceed 600L); add verification table with test-start lines
- Production LOC corrections (5+ locations each):
  launch.rs 1085→~1077, operator_env.rs 810→~880,
  app/mod.rs 928→~957, config/editor.rs 503→~584
- §2 OpPicker row: replace vague "no entry yet" with confirmed gap:
  PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10
  named); omits op_picker/, agent_picker.rs, scope_picker.rs,
  source_picker.rs and pre-dates the manager/ sub-structure split

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 32 — two-tier spec arch, behavioral spec template

- §8.1: Add two-tier spec architecture table distinguishing feature specs
  (public Starlight MDX, user-facing) from behavioral specs (internal
  docs/internal/specs/, for AI code verification) — resolves contradiction
  between §4 (which said docs/internal/specs/) and §8.1 (which said
  "no longer needed; specs are public")
- §8.1: Add concrete behavioral spec template for op_picker/ with state
  machine table and 3 INV invariant entries each with a grep-executable
  "Verify by:" command; template directly usable for the 3 Phase 1 specs
- §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim
- Confirmed render/editor.rs ~736L and render/list.rs ~668L production
  (no interspersed production code — all test blocks follow consecutively)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 33 — executive summary, §0 correctness

- §0: Add executive summary (~300 words) with core problem, 3-phase
  recommendation, key counter-argument, and navigation table pointing
  to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a
  readability roadmap with no entry-point orientation
- §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs
  current verified size; stale reference was in the first section readers see)
- §0 item 3: Add "(selective)" qualifier and explicit note that standard
  Rust co-locates struct+impl — impl-extension pattern is justified only
  for files >800L production, not as a universal rule

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 34 — spec priority reorder, §10 Phase 1 track

- §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //!
  doc, ~1077L production, critical path — all jackin load failures trace
  here); drop config/editor.rs from Phase 1 (its 963L test suite already
  serves as behavioral spec — tests are behavioral examples); reduce Phase
  1 from 3 specs to 2 specs; add reasoning for the priority ordering
- §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling
  setup) + Track B (Phase 1 behavioral spec authoring); Track B includes
  specific INV invariants to capture for runtime/launch.rs grounded in
  reading the actual function structure (step comment positions); adds
  sequencing rationale: spec must precede structural splits

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 35 — verified INV entries for runtime/launch.rs

Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from
iteration 34 (inferred from step comment positions) with 5 verified INVs
citing exact line numbers:
- INV-1: trust gate (line 594) precedes image build (line 736)
- INV-2: container name claimed (line 754) between image build and network
- INV-3: token verified (line 763) before network creation (line 827)
- INV-4: render_exit called at lines 886 AND 890 (all exit paths)
- INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup,
  crash→disarm (explains jackin hardline compatibility)
Corrected wrong line number: claim_container_name call is at 754, not 918
(918 is the function definition). Each INV has a grep-executable Verify by.

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 36 — CI gate for PROJECT_STRUCTURE.md freshness

§3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
three concrete options:
- Option A: CONTRIBUTING.md rule (necessary but insufficient)
- Option B: ci.yml git-diff-scoped shell check (recommended) — only checks
  files added in the current PR so it doesn't require fixing existing stale
  entries before merging; greps for module directory name in prose
- Option C: Structured TOML module registry (over-engineered for scale)
Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts
pattern already established in docs/scripts/

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iterations 36-37 — CI gate + greenfield workspace architecture

Iteration 36:
- §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
  3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry);
  recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded
  in existing check:repo-links.ts pattern from docs/scripts/

Iteration 37 (operator directive: greenfield Rust structure):
- §4: Add "Greenfield architecture — ideal structure for a growing project"
  section based on verified cross-module dependency graph (grep iteration 37)
- Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0;
  config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3
- Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace
  types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config)
- Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui,
  jackin-runtime, jackin-console, jackin-shell + thin binary
- Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary
- Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 38 — Rust workspace standards, community evidence

Ground workspace recommendation in real-world project research:
- ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers
- starship and fd-find stay single-crate at 1M+ LOC — no library use case
- jackin (43K LOC, no external consumers) maps to starship/fd pattern
  → single-crate is community-standard; "stay single-crate" recommendation confirmed

Update greenfield workspace structure to follow matklad's pattern:
- Virtual manifest at root (no [package] in root Cargo.toml)
- Flat crates/ directory (not nested); crate names match folder names
- version = "0.0.0" for unpublished internal crates
- Add inline dep comments to each crate in the ASCII structure

Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings +
Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): revise §7.9 + §3 — adopt per-directory README.md

§7.9: Reverse previous "reject" recommendation to "adopt" per-directory
README.md for major src/ module directories. Rationale: README.md is
AI-native — Claude Code, Copilot, Cursor load it automatically on directory
entry, giving AI agents orientation before they decide which file to open.
PROJECT_STRUCTURE.md being confirmed stale removes the main argument for
the "single root file" approach.

Add three-layer documentation model table:
- README.md: directory orientation (AI + human, on entry)
- AGENTS.md: agent workflow rules (root, session start)
- CLAUDE.md: @AGENTS.md pointer only — NEVER add content here
- //! docs: file-level contracts (when reading/editing)

Add specific README.md content targets for 7 directories
(src/, src/runtime/, src/console/, src/console/manager/,
src/console/widgets/, docs/, docs/internal/).

§3 target document shape: Add per-directory README.md to proposed
hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md
design principle (single-line @AGENTS.md — never duplicate content).

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): internal docs are browsable — unified Starlight site

Operator directive: internal docs (architecture, specs, ADRs, roadmap) should
be browsable, not hidden filesystem files. They are a different TYPE of docs
focused on implementation details and vision, published as a "Developer
Reference" section of the Starlight site.

§3 target document shape:
- docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages)
- Browsable at jackin.tailrocks.com/internal/
- Sidebar: "Developer Reference" group (collapsed by default) with sub-sections
  for architecture, code-tour, contributing, testing, decisions, specs, roadmap
- Include astro.config.ts sidebar config snippet

§8.1 two-tier spec distinction eliminated:
- Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/
- Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location
- Both browsable and searchable via Starlight; AI agents can be pointed to URLs

§8.3 + §4:
- All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/
- ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable)
- README.md pointer for src/runtime/ updated to URL reference

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): §11 — modern Rust docs platform (future project)

Add §11 capturing the vision for a modern docs.rs alternative with:
- rustdoc JSON ingestion → Astro Starlight presentation
- MCP server for AI agent queries (Context7 alternative for Rust)
- Rust-specific query types: rust_get_context(), rust_find_impls(),
  rust_search_types() — things Context7 cannot provide
- Comparison table vs Context7
- Architecture diagram (ingestion → processing → Starlight + MCP)
- Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs
- Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional
  prototype for the platform's processing and presentation layers

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 39 — update §0, fix stale internal/ paths

§0 executive summary: rewrite to reflect decisions from iterations 30-38:
- browsable internal docs (jackin.tailrocks.com/internal/)
- per-directory README.md adoption (§7.9 reversed)
- CLAUDE.md = @AGENTS.md single-line pointer only
- greenfield workspace architecture (matklad's virtual manifest pattern)
- §11 future project: modern Rust docs platform / Context7-for-Rust
- document size 1800+ → 2200+

Fix stale docs/internal/ bare paths not caught by iteration 38 sweep:
- Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths
- §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path
- §10 Track B item 2: op-picker spec path → Starlight MDX

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 40 — §7.15 pipeline + Rule 4 pub audit

§7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline
- Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended)
  / rustdoc-json crate as Rust binary
- Option B recommended: matches existing docs/scripts/ pattern, nightly
  isolated to separate CI step, zero effect on stable build
- Key design: URL at /internal/api/, cross-links to behavioral specs,
  Starlight unified search, prototype for §11 future project
- Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit
- Recommend: adopt after Phase 1 //! sprint (value ∝ coverage)

§4 Rule 4 pub discipline: replace estimated "50-100 items" guess with
verified numbers from iteration 40 grep:
- 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files
- 0 uses of unreachable_pub lint — no enforcement gate
- Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8)
- Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn"
- Revised scope: ~150-200 mechanical conversions (excludes entry points)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): split research into 19 actionable items

Delete _research_notes.md (no longer needed).

Replace 2343L READABILITY_AND_MODERNIZATION.md with:
- README.md: index of all 19 items with phase, ordering notes, links
- READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L)
- items/ITEM-001 through ITEM-019: individual actionable items

Items by phase:
  Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011
  Phase 1 (needs confirmation): ITEM-005, 016, 018
  Phase 2 (structural splits, confirmation required): ITEM-012..015
  Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace)

Each item has: summary, key files with line numbers, steps, what
needs confirmation, and relevant research backing from the 40-iteration
analysis loop.

Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): migrate 19 items to Starlight reference/roadmap section

Move all codebase health roadmap items from docs/internal/roadmap/items/
(plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/
(MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/).

Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to
astro.config.ts. Deletes the old items/ directory. Updates the internal
README to redirect to the new location.

Also adds codebase-readability.mdx — a new overview item that captures
the overall readability/restructuring program with a recommended execution
order: file splits first, then greenfield workspace, then per-directory
README+AGENTS.md, then docs and specs.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>

* docs(roadmap): remove premature internal/roadmap/README.md

The internal/ structure doesn't exist yet — it will be created as part
of the roadmap items themselves. No need for a redirect stub now.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>

* docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive

All content has been distilled into the individual Starlight roadmap pages.
The full 2343L research is preserved in git history at commit b7e9fc2.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>

* docs(roadmap): fix check:repo-links errors + remove iteration log

- Replace plain code spans with <RepoFile> for validate.rs, mise.toml,
  Cargo.toml, and op_picker/mod.rs
- Remove deleted READABILITY_AND_MODERNIZATION.md reference from
  codebase-readability.mdx
- Delete _iteration_log.md (git history is the archive)

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>

* docs(roadmap): fix lychee false-positive link in move-contributing-testing

The example redirect text contained a markdown hyperlink to a proposed
future file path that doesn't exist yet. Changed to a code span.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>

---------

Signed-off-by: Alexey Zhokhov <alexey@chainargos.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Codex <codex@openai.com>

…183)

* docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec

Primary goal shift: codebase must be verifiable for AI-generated code.

- §0: replace generic description with explicit verifiability rationale
  (module contracts, localised concerns, types/behaviour separation)
- §4 intro: add "Why structure matters for AI-generated code" section with
  audit-units table mapping each post-split file to one reviewable question
- §4 4a: expand config/types.rs from description to full execution spec —
  exact type list, post-split mod.rs content, zero-change submodule
  guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T
  which resolves through mod.rs re-exports unchanged), impl-extension
  pattern already in use documented


* docs(roadmap): iteration 14 — editor method map, app helpers, //! queue

- §4 4c: config/editor.rs split is now execution-ready — complete
  6-file method-to-file table with private helper placement verified
  (validate_candidate→io.rs, table_path_mut→mod.rs pub(super),
  auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig)
- §4 4e: app/mod.rs split complete — all private helpers mapped
  (parse_auth_forward_mode_from_cli→config_cmd.rs,
  workspace_env_scope→workspace_cmd.rs, print_env_table note,
  remove_data_dir_if_exists→dispatch.rs)
- §10 step 5: add //! priority queue — 10 files with draft content,
  prioritised by cold-landing impact and AI audit risk; selector.rs
  and instance/mod.rs explicitly document the /→__ invariant


* docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed

- §4 4d: correct operator_env dependency graph — layers.rs imports
  both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable
  resolve_operator_env wrapper at line 797); still a valid DAG
- §4 4f: verify trust.rs split safety — FnOnce injection pattern means
  launch_pipeline.rs has zero dependency on trust.rs; import chain
  documented; trust bypass audit now requires reading only ~60L
- §9 OQ1 closed: op_cache.rs read in full — 4-level structure,
  per-level invalidation, no TTL/expiry (expiry handled at OpCli
  subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented


* docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence

- Fix duplicate Rule 3 section introduced by previous edit; add docker.rs
  co-location note as third edge case (three edge cases, not two)
- Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171
  (was listed as 782L); propose 6-file tab-by-tab split with auditability
  note on the security-adjacent Secrets tab
- Add §10 execution-order note: 4a and 4c are independent — editor.rs
  imports AppConfig via crate::config re-exports regardless of 4a order
- Append iteration 16 log entry with confidence table and weakest sections


* docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections

- Add instance/auth.rs to //! priority queue at #4: four security
  invariants (0o600 perms, symlink rejection, TOCTOU-safe writes,
  macOS Keychain) documented in draft //! content
- Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types
  mixed with impl blocks; propose 5-file types/behavior split
- Correct stale line counts: render/list.rs 1122→1989 (PR #171 added
  render_environments_subpanel); state.rs 865→992; priorities upgraded
- Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332,
  mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944
- Renumber //! priority queue to 11 entries (was 10)


* docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal

- Close OQ2: agent_allow.rs read in full — 55L, correct //! doc,
  design sound; serves as model for //! priority queue pattern
- Add render/list.rs as new Rule 5 violator: 668L production (PR #171
  added render_environments_subpanel); propose 3-file split (mod.rs,
  details.rs, subpanels.rs); note import-path change for agents_block_agent_count
- Update §1 module map: agent_allow.rs entry corrected with size/API


* docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal

- Correct input/editor.rs: 2349L total (was 1304L), 1141L production
  (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn
  handle_editor_modal at line 618 was invisible to previous grep pattern;
  now the largest production file in the codebase; priority → Critical
- Correct input/save.rs: 1472L total, 661L production (was 567L)
- Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers),
  secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs
- Update key insight paragraph naming input/editor.rs as largest production file


* docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict

- Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority
  order; rename existing 4f (launch.rs) → 4g; add circular-import risk note
  for ManagerStage/EditorState split sequencing
- Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid
  is a tightly-coupled rendering loop); section comments compensate for missing //!
- Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs;
  within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable)


* docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections

- Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file
  split (mod.rs + flow.rs + preview.rs); no cross-dependency between
  flow and preview groups; §10 4f-v updated from Optional to concrete plan
- Fix //! queue preamble: "first 10 files" → "first 11 files"
- Correct save.rs module map (1418→1472L, correct key exports) and
  hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save
  is the Phase 2 partner at ~149L)


* docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis

- Analyze input/list.rs: 214L production (tests at 215); has //! doc;
  two focused pub(super) fns; no split needed; Low priority; correct module map
- Add mount_info.rs to hot-spot table: 277L production; Low priority;
  has //! doc; correct module map with 3 public enums + inspect fn
- Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists


* docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected

- Expand audit units table from 8 to 13 entries: add state/types.rs,
  state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs,
  input/save/preview.rs — all targeting PR #171 AI-generated console code
- Add PR #171 context note linking 5 new entries to AI-generated code concern
- Correct input/mod.rs module map: 369L, add InputOutcome enum to exports
- Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct


* docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed

- Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded
  1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element
  (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted
- Correct render/mod.rs module map: 421L; FooterItem + palette constants
  + render_header + centered_rect_fixed added to key exports
- Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum)
  vs "Secrets / Environments" (UI label); /stub qualifier already removed


* docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat

- Correct too_many_lines count: 13 across 8 → 16 across 11 files
  (PR #171 added 5 suppressions in console/manager); add full breakdown
  table; update all 3 occurrences in roadmap
- Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow)
- Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description


* docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed

- Add console/mod.rs to hot-spot table: 406L/307L production (Low);
  correct module map from ~200 → 406L; note missing //! doc with
  ConsoleStage design block comment worth promoting
- Add op_picker/render.rs to hot-spot table: 865L/545L production
  (Medium); PR #171 AI-generated; 14 functions in two logical groups
  (entry/helpers vs level renderers); split into levels.rs proposed
- Correct 3 stale ~200L estimates for console/mod.rs across roadmap


* docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction

- Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High);
  PR #171 AI-generated; OpPickerState types+behavior split opportunity;
  has 7-line //! doc; module map split into two rows (mod.rs + render.rs)
- Add op_picker/render.rs 2-file split proposal: render.rs (coordinator)
  + render_pane.rs (pane/level renderers); no cross-dependency confirmed
- Correct operator_env.rs total: 1569→2130L (880L production); update
  4 occurrences across hot-spot table, ASCII tree, §4 analysis


* docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections

- Add op_picker/mod.rs formal 3-file split: loading.rs (async load family
  ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors)
- Correct "24 files" → "28+" for 500L threshold count
- Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note)


* docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis

- §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs
  → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs →
  render.rs + pane.rs); document impl-extension and import-path caveats
- §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files
  have //! docs, no file exceeds ~350L production; classified as exemplar
  (not a split candidate); document git_prompt.rs coupling-density
  justification and input.rs as 28-file false positive (144L production)
- §1 module map: expand single file_browser/ row to 5 individual rows
  with production LOC and dominant concern per file


* docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections

- §4: Add "Alternative thesis: documentation-first verification" — challenges
  the two core assumptions behind file splitting (files-as-audit-unit and
  file-size-as-context-constraint); adds 7-criterion comparison table vs
  structure-first approach; introduces phased combined recommendation:
  Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs,
  zero structural change); Phase 2 = splits only for >600L production files
  (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K
- Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and
  8 locations respectively; verified by fresh find|xargs wc -l scan)
- §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L),
  source_picker.rs (244L) — all PR #171 additions with //! docs


* docs(roadmap): iteration 31 — fix 600L→800L threshold error, correct LOC

- §4 alternative thesis: correct ">600L production → 4 files" claim
  introduced in iteration 30; re-verified all 9 candidate files via
  #[cfg(test)] line position; threshold must be >800L to get exactly 4
  files (9 exceed 600L); add verification table with test-start lines
- Production LOC corrections (5+ locations each):
  launch.rs 1085→~1077, operator_env.rs 810→~880,
  app/mod.rs 928→~957, config/editor.rs 503→~584
- §2 OpPicker row: replace vague "no entry yet" with confirmed gap:
  PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10
  named); omits op_picker/, agent_picker.rs, scope_picker.rs,
  source_picker.rs and pre-dates the manager/ sub-structure split


* docs(roadmap): iteration 32 — two-tier spec arch, behavioral spec template

- §8.1: Add two-tier spec architecture table distinguishing feature specs
  (public Starlight MDX, user-facing) from behavioral specs (internal
  docs/internal/specs/, for AI code verification) — resolves contradiction
  between §4 (which said docs/internal/specs/) and §8.1 (which said
  "no longer needed; specs are public")
- §8.1: Add concrete behavioral spec template for op_picker/ with state
  machine table and 3 INV invariant entries each with a grep-executable
  "Verify by:" command; template directly usable for the 3 Phase 1 specs
- §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim
- Confirmed render/editor.rs ~736L and render/list.rs ~668L production
  (no interspersed production code — all test blocks follow consecutively)


* docs(roadmap): iteration 33 — executive summary, §0 correctness

- §0: Add executive summary (~300 words) with core problem, 3-phase
  recommendation, key counter-argument, and navigation table pointing
  to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a
  readability roadmap with no entry-point orientation
- §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs
  current verified size; stale reference was in the first section readers see)
- §0 item 3: Add "(selective)" qualifier and explicit note that standard
  Rust co-locates struct+impl — impl-extension pattern is justified only
  for files >800L production, not as a universal rule


* docs(roadmap): iteration 34 — spec priority reorder, §10 Phase 1 track

- §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //!
  doc, ~1077L production, critical path — all jackin load failures trace
  here); drop config/editor.rs from Phase 1 (its 963L test suite already
  serves as behavioral spec — tests are behavioral examples); reduce Phase
  1 from 3 specs to 2 specs; add reasoning for the priority ordering
- §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling
  setup) + Track B (Phase 1 behavioral spec authoring); Track B includes
  specific INV invariants to capture for runtime/launch.rs grounded in
  reading the actual function structure (step comment positions); adds
  sequencing rationale: spec must precede structural splits


* docs(roadmap): iteration 35 — verified INV entries for runtime/launch.rs

Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from
iteration 34 (inferred from step comment positions) with 5 verified INVs
citing exact line numbers:
- INV-1: trust gate (line 594) precedes image build (line 736)
- INV-2: container name claimed (line 754) between image build and network
- INV-3: token verified (line 763) before network creation (line 827)
- INV-4: render_exit called at lines 886 AND 890 (all exit paths)
- INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup,
  crash→disarm (explains jackin hardline compatibility)
Corrected wrong line number: claim_container_name call is at 754, not 918
(918 is the function definition). Each INV has a grep-executable Verify by.


* docs(roadmap): iteration 36 — CI gate for PROJECT_STRUCTURE.md freshness

§3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
three concrete options:
- Option A: CONTRIBUTING.md rule (necessary but insufficient)
- Option B: ci.yml git-diff-scoped shell check (recommended) — only checks
  files added in the current PR so it doesn't require fixing existing stale
  entries before merging; greps for module directory name in prose
- Option C: Structured TOML module registry (over-engineered for scale)
Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts
pattern already established in docs/scripts/


* docs(roadmap): iterations 36-37 — CI gate + greenfield workspace architecture

Iteration 36:
- §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
  3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry);
  recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded
  in existing check:repo-links.ts pattern from docs/scripts/

Iteration 37 (operator directive: greenfield Rust structure):
- §4: Add "Greenfield architecture — ideal structure for a growing project"
  section based on verified cross-module dependency graph (grep iteration 37)
- Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0;
  config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3
- Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace
  types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config)
- Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui,
  jackin-runtime, jackin-console, jackin-shell + thin binary
- Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary
- Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration


* docs(roadmap): iteration 38 — Rust workspace standards, community evidence

Ground workspace recommendation in real-world project research:
- ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers
- starship and fd-find stay single-crate at 1M+ LOC — no library use case
- jackin (43K LOC, no external consumers) maps to starship/fd pattern
  → single-crate is community-standard; "stay single-crate" recommendation confirmed

Update greenfield workspace structure to follow matklad's pattern:
- Virtual manifest at root (no [package] in root Cargo.toml)
- Flat crates/ directory (not nested); crate names match folder names
- version = "0.0.0" for unpublished internal crates
- Add inline dep comments to each crate in the ASCII structure

Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings +
Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22)


* docs(roadmap): revise §7.9 + §3 — adopt per-directory README.md

§7.9: Reverse previous "reject" recommendation to "adopt" per-directory
README.md for major src/ module directories. Rationale: README.md is
AI-native — Claude Code, Copilot, Cursor load it automatically on directory
entry, giving AI agents orientation before they decide which file to open.
PROJECT_STRUCTURE.md being confirmed stale removes the main argument for
the "single root file" approach.

Add three-layer documentation model table:
- README.md: directory orientation (AI + human, on entry)
- AGENTS.md: agent workflow rules (root, session start)
- CLAUDE.md: @AGENTS.md pointer only — NEVER add content here
- //! docs: file-level contracts (when reading/editing)

Add specific README.md content targets for 7 directories
(src/, src/runtime/, src/console/, src/console/manager/,
src/console/widgets/, docs/, docs/internal/).

§3 target document shape: Add per-directory README.md to proposed
hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md
design principle (single-line @AGENTS.md — never duplicate content).


* docs(roadmap): internal docs are browsable — unified Starlight site

Operator directive: internal docs (architecture, specs, ADRs, roadmap) should
be browsable, not hidden filesystem files. They are a different TYPE of docs
focused on implementation details and vision, published as a "Developer
Reference" section of the Starlight site.

§3 target document shape:
- docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages)
- Browsable at jackin.tailrocks.com/internal/
- Sidebar: "Developer Reference" group (collapsed by default) with sub-sections
  for architecture, code-tour, contributing, testing, decisions, specs, roadmap
- Include astro.config.ts sidebar config snippet

§8.1 two-tier spec distinction eliminated:
- Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/
- Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location
- Both browsable and searchable via Starlight; AI agents can be pointed to URLs

§8.3 + §4:
- All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/
- ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable)
- README.md pointer for src/runtime/ updated to URL reference


* docs(roadmap): §11 — modern Rust docs platform (future project)

Add §11 capturing the vision for a modern docs.rs alternative with:
- rustdoc JSON ingestion → Astro Starlight presentation
- MCP server for AI agent queries (Context7 alternative for Rust)
- Rust-specific query types: rust_get_context(), rust_find_impls(),
  rust_search_types() — things Context7 cannot provide
- Comparison table vs Context7
- Architecture diagram (ingestion → processing → Starlight + MCP)
- Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs
- Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional
  prototype for the platform's processing and presentation layers


* docs(roadmap): iteration 39 — update §0, fix stale internal/ paths

§0 executive summary: rewrite to reflect decisions from iterations 30-38:
- browsable internal docs (jackin.tailrocks.com/internal/)
- per-directory README.md adoption (§7.9 reversed)
- CLAUDE.md = @AGENTS.md single-line pointer only
- greenfield workspace architecture (matklad's virtual manifest pattern)
- §11 future project: modern Rust docs platform / Context7-for-Rust
- document size 1800+ → 2200+

Fix stale docs/internal/ bare paths not caught by iteration 38 sweep:
- Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths
- §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path
- §10 Track B item 2: op-picker spec path → Starlight MDX


* docs(roadmap): iteration 40 — §7.15 pipeline + Rule 4 pub audit

§7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline
- Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended)
  / rustdoc-json crate as Rust binary
- Option B recommended: matches existing docs/scripts/ pattern, nightly
  isolated to separate CI step, zero effect on stable build
- Key design: URL at /internal/api/, cross-links to behavioral specs,
  Starlight unified search, prototype for §11 future project
- Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit
- Recommend: adopt after Phase 1 //! sprint (value ∝ coverage)

§4 Rule 4 pub discipline: replace estimated "50-100 items" guess with
verified numbers from iteration 40 grep:
- 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files
- 0 uses of unreachable_pub lint — no enforcement gate
- Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8)
- Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn"
- Revised scope: ~150-200 mechanical conversions (excludes entry points)


* docs(roadmap): split research into 19 actionable items

Delete _research_notes.md (no longer needed).

Replace 2343L READABILITY_AND_MODERNIZATION.md with:
- README.md: index of all 19 items with phase, ordering notes, links
- READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L)
- items/ITEM-001 through ITEM-019: individual actionable items

Items by phase:
  Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011
  Phase 1 (needs confirmation): ITEM-005, 016, 018
  Phase 2 (structural splits, confirmation required): ITEM-012..015
  Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace)

Each item has: summary, key files with line numbers, steps, what
needs confirmation, and relevant research backing from the 40-iteration
analysis loop.


* docs(roadmap): migrate 19 items to Starlight reference/roadmap section

Move all codebase health roadmap items from docs/internal/roadmap/items/
(plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/
(MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/).

Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to
astro.config.ts. Deletes the old items/ directory. Updates the internal
README to redirect to the new location.

Also adds codebase-readability.mdx — a new overview item that captures
the overall readability/restructuring program with a recommended execution
order: file splits first, then greenfield workspace, then per-directory
README+AGENTS.md, then docs and specs.


* docs(roadmap): remove premature internal/roadmap/README.md

The internal/ structure doesn't exist yet — it will be created as part
of the roadmap items themselves. No need for a redirect stub now.


* docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive

All content has been distilled into the individual Starlight roadmap pages.
The full 2343L research is preserved in git history at commit b7e9fc2.


* docs(roadmap): fix check:repo-links errors + remove iteration log

- Replace plain code spans with <RepoFile> for validate.rs, mise.toml,
  Cargo.toml, and op_picker/mod.rs
- Remove deleted READABILITY_AND_MODERNIZATION.md reference from
  codebase-readability.mdx
- Delete _iteration_log.md (git history is the archive)


* docs(roadmap): fix lychee false-positive link in move-contributing-testing

The example redirect text contained a markdown hyperlink to a proposed
future file path that doesn't exist yet. Changed to a code span.


---------

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>

…183)

* docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec

Primary goal shift: codebase must be verifiable for AI-generated code.

- §0: replace generic description with explicit verifiability rationale
  (module contracts, localised concerns, types/behaviour separation)
- §4 intro: add "Why structure matters for AI-generated code" section with
  audit-units table mapping each post-split file to one reviewable question
- §4 4a: expand config/types.rs from description to full execution spec —
  exact type list, post-split mod.rs content, zero-change submodule
  guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T
  which resolves through mod.rs re-exports unchanged), impl-extension
  pattern already in use documented


* docs(roadmap): iteration 14 — editor method map, app helpers, //! queue

- §4 4c: config/editor.rs split is now execution-ready — complete
  6-file method-to-file table with private helper placement verified
  (validate_candidate→io.rs, table_path_mut→mod.rs pub(super),
  auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig)
- §4 4e: app/mod.rs split complete — all private helpers mapped
  (parse_auth_forward_mode_from_cli→config_cmd.rs,
  workspace_env_scope→workspace_cmd.rs, print_env_table note,
  remove_data_dir_if_exists→dispatch.rs)
- §10 step 5: add //! priority queue — 10 files with draft content,
  prioritised by cold-landing impact and AI audit risk; selector.rs
  and instance/mod.rs explicitly document the /→__ invariant


* docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed

- §4 4d: correct operator_env dependency graph — layers.rs imports
  both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable
  resolve_operator_env wrapper at line 797); still a valid DAG
- §4 4f: verify trust.rs split safety — FnOnce injection pattern means
  launch_pipeline.rs has zero dependency on trust.rs; import chain
  documented; trust bypass audit now requires reading only ~60L
- §9 OQ1 closed: op_cache.rs read in full — 4-level structure,
  per-level invalidation, no TTL/expiry (expiry handled at OpCli
  subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented


* docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence

- Fix duplicate Rule 3 section introduced by previous edit; add docker.rs
  co-location note as third edge case (three edge cases, not two)
- Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171
  (was listed as 782L); propose 6-file tab-by-tab split with auditability
  note on the security-adjacent Secrets tab
- Add §10 execution-order note: 4a and 4c are independent — editor.rs
  imports AppConfig via crate::config re-exports regardless of 4a order
- Append iteration 16 log entry with confidence table and weakest sections


* docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections

- Add instance/auth.rs to //! priority queue at #4: four security
  invariants (0o600 perms, symlink rejection, TOCTOU-safe writes,
  macOS Keychain) documented in draft //! content
- Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types
  mixed with impl blocks; propose 5-file types/behavior split
- Correct stale line counts: render/list.rs 1122→1989 (PR #171 added
  render_environments_subpanel); state.rs 865→992; priorities upgraded
- Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332,
  mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944
- Renumber //! priority queue to 11 entries (was 10)


* docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal

- Close OQ2: agent_allow.rs read in full — 55L, correct //! doc,
  design sound; serves as model for //! priority queue pattern
- Add render/list.rs as new Rule 5 violator: 668L production (PR #171
  added render_environments_subpanel); propose 3-file split (mod.rs,
  details.rs, subpanels.rs); note import-path change for agents_block_agent_count
- Update §1 module map: agent_allow.rs entry corrected with size/API


* docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal

- Correct input/editor.rs: 2349L total (was 1304L), 1141L production
  (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn
  handle_editor_modal at line 618 was invisible to previous grep pattern;
  now the largest production file in the codebase; priority → Critical
- Correct input/save.rs: 1472L total, 661L production (was 567L)
- Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers),
  secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs
- Update key insight paragraph naming input/editor.rs as largest production file


* docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict

- Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority
  order; rename existing 4f (launch.rs) → 4g; add circular-import risk note
  for ManagerStage/EditorState split sequencing
- Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid
  is a tightly-coupled rendering loop); section comments compensate for missing //!
- Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs;
  within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable)


* docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections

- Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file
  split (mod.rs + flow.rs + preview.rs); no cross-dependency between
  flow and preview groups; §10 4f-v updated from Optional to concrete plan
- Fix //! queue preamble: "first 10 files" → "first 11 files"
- Correct save.rs module map (1418→1472L, correct key exports) and
  hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save
  is the Phase 2 partner at ~149L)


* docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis

- Analyze input/list.rs: 214L production (tests at 215); has //! doc;
  two focused pub(super) fns; no split needed; Low priority; correct module map
- Add mount_info.rs to hot-spot table: 277L production; Low priority;
  has //! doc; correct module map with 3 public enums + inspect fn
- Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists


* docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected

- Expand audit units table from 8 to 13 entries: add state/types.rs,
  state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs,
  input/save/preview.rs — all targeting PR #171 AI-generated console code
- Add PR #171 context note linking 5 new entries to AI-generated code concern
- Correct input/mod.rs module map: 369L, add InputOutcome enum to exports
- Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct


* docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed

- Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded
  1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element
  (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted
- Correct render/mod.rs module map: 421L; FooterItem + palette constants
  + render_header + centered_rect_fixed added to key exports
- Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum)
  vs "Secrets / Environments" (UI label); /stub qualifier already removed


* docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat

- Correct too_many_lines count: 13 across 8 → 16 across 11 files
  (PR #171 added 5 suppressions in console/manager); add full breakdown
  table; update all 3 occurrences in roadmap
- Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow)
- Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description


* docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed

- Add console/mod.rs to hot-spot table: 406L/307L production (Low);
  correct module map from ~200 → 406L; note missing //! doc with
  ConsoleStage design block comment worth promoting
- Add op_picker/render.rs to hot-spot table: 865L/545L production
  (Medium); PR #171 AI-generated; 14 functions in two logical groups
  (entry/helpers vs level renderers); split into levels.rs proposed
- Correct 3 stale ~200L estimates for console/mod.rs across roadmap


* docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction

- Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High);
  PR #171 AI-generated; OpPickerState types+behavior split opportunity;
  has 7-line //! doc; module map split into two rows (mod.rs + render.rs)
- Add op_picker/render.rs 2-file split proposal: render.rs (coordinator)
  + render_pane.rs (pane/level renderers); no cross-dependency confirmed
- Correct operator_env.rs total: 1569→2130L (880L production); update
  4 occurrences across hot-spot table, ASCII tree, §4 analysis


* docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections

- Add op_picker/mod.rs formal 3-file split: loading.rs (async load family
  ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors)
- Correct "24 files" → "28+" for 500L threshold count
- Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note)


* docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis

- §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs
  → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs →
  render.rs + pane.rs); document impl-extension and import-path caveats
- §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files
  have //! docs, no file exceeds ~350L production; classified as exemplar
  (not a split candidate); document git_prompt.rs coupling-density
  justification and input.rs as 28-file false positive (144L production)
- §1 module map: expand single file_browser/ row to 5 individual rows
  with production LOC and dominant concern per file


* docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections

- §4: Add "Alternative thesis: documentation-first verification" — challenges
  the two core assumptions behind file splitting (files-as-audit-unit and
  file-size-as-context-constraint); adds 7-criterion comparison table vs
  structure-first approach; introduces phased combined recommendation:
  Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs,
  zero structural change); Phase 2 = splits only for >600L production files
  (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K
- Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and
  8 locations respectively; verified by fresh find|xargs wc -l scan)
- §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L),
  source_picker.rs (244L) — all PR #171 additions with //! docs


* docs(roadmap): iteration 31 — fix 600L→800L threshold error, correct LOC

- §4 alternative thesis: correct ">600L production → 4 files" claim
  introduced in iteration 30; re-verified all 9 candidate files via
  #[cfg(test)] line position; threshold must be >800L to get exactly 4
  files (9 exceed 600L); add verification table with test-start lines
- Production LOC corrections (5+ locations each):
  launch.rs 1085→~1077, operator_env.rs 810→~880,
  app/mod.rs 928→~957, config/editor.rs 503→~584
- §2 OpPicker row: replace vague "no entry yet" with confirmed gap:
  PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10
  named); omits op_picker/, agent_picker.rs, scope_picker.rs,
  source_picker.rs and pre-dates the manager/ sub-structure split


* docs(roadmap): iteration 32 — two-tier spec arch, behavioral spec template

- §8.1: Add two-tier spec architecture table distinguishing feature specs
  (public Starlight MDX, user-facing) from behavioral specs (internal
  docs/internal/specs/, for AI code verification) — resolves contradiction
  between §4 (which said docs/internal/specs/) and §8.1 (which said
  "no longer needed; specs are public")
- §8.1: Add concrete behavioral spec template for op_picker/ with state
  machine table and 3 INV invariant entries each with a grep-executable
  "Verify by:" command; template directly usable for the 3 Phase 1 specs
- §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim
- Confirmed render/editor.rs ~736L and render/list.rs ~668L production
  (no interspersed production code — all test blocks follow consecutively)


* docs(roadmap): iteration 33 — executive summary, §0 correctness

- §0: Add executive summary (~300 words) with core problem, 3-phase
  recommendation, key counter-argument, and navigation table pointing
  to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a
  readability roadmap with no entry-point orientation
- §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs
  current verified size; stale reference was in the first section readers see)
- §0 item 3: Add "(selective)" qualifier and explicit note that standard
  Rust co-locates struct+impl — impl-extension pattern is justified only
  for files >800L production, not as a universal rule


* docs(roadmap): iteration 34 — spec priority reorder, §10 Phase 1 track

- §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //!
  doc, ~1077L production, critical path — all jackin load failures trace
  here); drop config/editor.rs from Phase 1 (its 963L test suite already
  serves as behavioral spec — tests are behavioral examples); reduce Phase
  1 from 3 specs to 2 specs; add reasoning for the priority ordering
- §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling
  setup) + Track B (Phase 1 behavioral spec authoring); Track B includes
  specific INV invariants to capture for runtime/launch.rs grounded in
  reading the actual function structure (step comment positions); adds
  sequencing rationale: spec must precede structural splits


* docs(roadmap): iteration 35 — verified INV entries for runtime/launch.rs

Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from
iteration 34 (inferred from step comment positions) with 5 verified INVs
citing exact line numbers:
- INV-1: trust gate (line 594) precedes image build (line 736)
- INV-2: container name claimed (line 754) between image build and network
- INV-3: token verified (line 763) before network creation (line 827)
- INV-4: render_exit called at lines 886 AND 890 (all exit paths)
- INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup,
  crash→disarm (explains jackin hardline compatibility)
Corrected wrong line number: claim_container_name call is at 754, not 918
(918 is the function definition). Each INV has a grep-executable Verify by.


* docs(roadmap): iteration 36 — CI gate for PROJECT_STRUCTURE.md freshness

§3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
three concrete options:
- Option A: CONTRIBUTING.md rule (necessary but insufficient)
- Option B: ci.yml git-diff-scoped shell check (recommended) — only checks
  files added in the current PR so it doesn't require fixing existing stale
  entries before merging; greps for module directory name in prose
- Option C: Structured TOML module registry (over-engineered for scale)
Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts
pattern already established in docs/scripts/


* docs(roadmap): iterations 36-37 — CI gate + greenfield workspace architecture

Iteration 36:
- §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with
  3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry);
  recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded
  in existing check:repo-links.ts pattern from docs/scripts/

Iteration 37 (operator directive: greenfield Rust structure):
- §4: Add "Greenfield architecture — ideal structure for a growing project"
  section based on verified cross-module dependency graph (grep iteration 37)
- Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0;
  config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3
- Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace
  types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config)
- Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui,
  jackin-runtime, jackin-console, jackin-shell + thin binary
- Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary
- Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration


* docs(roadmap): iteration 38 — Rust workspace standards, community evidence

Ground workspace recommendation in real-world project research:
- ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers
- starship and fd-find stay single-crate at 1M+ LOC — no library use case
- jackin (43K LOC, no external consumers) maps to starship/fd pattern
  → single-crate is community-standard; "stay single-crate" recommendation confirmed

Update greenfield workspace structure to follow matklad's pattern:
- Virtual manifest at root (no [package] in root Cargo.toml)
- Flat crates/ directory (not nested); crate names match folder names
- version = "0.0.0" for unpublished internal crates
- Add inline dep comments to each crate in the ASCII structure

Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings +
Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22)


* docs(roadmap): revise §7.9 + §3 — adopt per-directory README.md

§7.9: Reverse previous "reject" recommendation to "adopt" per-directory
README.md for major src/ module directories. Rationale: README.md is
AI-native — Claude Code, Copilot, Cursor load it automatically on directory
entry, giving AI agents orientation before they decide which file to open.
PROJECT_STRUCTURE.md being confirmed stale removes the main argument for
the "single root file" approach.

Add three-layer documentation model table:
- README.md: directory orientation (AI + human, on entry)
- AGENTS.md: agent workflow rules (root, session start)
- CLAUDE.md: @AGENTS.md pointer only — NEVER add content here
- //! docs: file-level contracts (when reading/editing)

Add specific README.md content targets for 7 directories
(src/, src/runtime/, src/console/, src/console/manager/,
src/console/widgets/, docs/, docs/internal/).

§3 target document shape: Add per-directory README.md to proposed
hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md
design principle (single-line @AGENTS.md — never duplicate content).


* docs(roadmap): internal docs are browsable — unified Starlight site

Operator directive: internal docs (architecture, specs, ADRs, roadmap) should
be browsable, not hidden filesystem files. They are a different TYPE of docs
focused on implementation details and vision, published as a "Developer
Reference" section of the Starlight site.

§3 target document shape:
- docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages)
- Browsable at jackin.tailrocks.com/internal/
- Sidebar: "Developer Reference" group (collapsed by default) with sub-sections
  for architecture, code-tour, contributing, testing, decisions, specs, roadmap
- Include astro.config.ts sidebar config snippet

§8.1 two-tier spec distinction eliminated:
- Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/
- Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location
- Both browsable and searchable via Starlight; AI agents can be pointed to URLs

§8.3 + §4:
- All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/
- ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable)
- README.md pointer for src/runtime/ updated to URL reference


* docs(roadmap): §11 — modern Rust docs platform (future project)

Add §11 capturing the vision for a modern docs.rs alternative with:
- rustdoc JSON ingestion → Astro Starlight presentation
- MCP server for AI agent queries (Context7 alternative for Rust)
- Rust-specific query types: rust_get_context(), rust_find_impls(),
  rust_search_types() — things Context7 cannot provide
- Comparison table vs Context7
- Architecture diagram (ingestion → processing → Starlight + MCP)
- Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs
- Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional
  prototype for the platform's processing and presentation layers


* docs(roadmap): iteration 39 — update §0, fix stale internal/ paths

§0 executive summary: rewrite to reflect decisions from iterations 30-38:
- browsable internal docs (jackin.tailrocks.com/internal/)
- per-directory README.md adoption (§7.9 reversed)
- CLAUDE.md = @AGENTS.md single-line pointer only
- greenfield workspace architecture (matklad's virtual manifest pattern)
- §11 future project: modern Rust docs platform / Context7-for-Rust
- document size 1800+ → 2200+

Fix stale docs/internal/ bare paths not caught by iteration 38 sweep:
- Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths
- §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path
- §10 Track B item 2: op-picker spec path → Starlight MDX


* docs(roadmap): iteration 40 — §7.15 pipeline + Rule 4 pub audit

§7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline
- Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended)
  / rustdoc-json crate as Rust binary
- Option B recommended: matches existing docs/scripts/ pattern, nightly
  isolated to separate CI step, zero effect on stable build
- Key design: URL at /internal/api/, cross-links to behavioral specs,
  Starlight unified search, prototype for §11 future project
- Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit
- Recommend: adopt after Phase 1 //! sprint (value ∝ coverage)

§4 Rule 4 pub discipline: replace estimated "50-100 items" guess with
verified numbers from iteration 40 grep:
- 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files
- 0 uses of unreachable_pub lint — no enforcement gate
- Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8)
- Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn"
- Revised scope: ~150-200 mechanical conversions (excludes entry points)


* docs(roadmap): split research into 19 actionable items

Delete _research_notes.md (no longer needed).

Replace 2343L READABILITY_AND_MODERNIZATION.md with:
- README.md: index of all 19 items with phase, ordering notes, links
- READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L)
- items/ITEM-001 through ITEM-019: individual actionable items

Items by phase:
  Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011
  Phase 1 (needs confirmation): ITEM-005, 016, 018
  Phase 2 (structural splits, confirmation required): ITEM-012..015
  Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace)

Each item has: summary, key files with line numbers, steps, what
needs confirmation, and relevant research backing from the 40-iteration
analysis loop.


* docs(roadmap): migrate 19 items to Starlight reference/roadmap section

Move all codebase health roadmap items from docs/internal/roadmap/items/
(plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/
(MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/).

Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to
astro.config.ts. Deletes the old items/ directory. Updates the internal
README to redirect to the new location.

Also adds codebase-readability.mdx — a new overview item that captures
the overall readability/restructuring program with a recommended execution
order: file splits first, then greenfield workspace, then per-directory
README+AGENTS.md, then docs and specs.


* docs(roadmap): remove premature internal/roadmap/README.md

The internal/ structure doesn't exist yet — it will be created as part
of the roadmap items themselves. No need for a redirect stub now.


* docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive

All content has been distilled into the individual Starlight roadmap pages.
The full 2343L research is preserved in git history at commit b7e9fc2.


* docs(roadmap): fix check:repo-links errors + remove iteration log

- Replace plain code spans with <RepoFile> for validate.rs, mise.toml,
  Cargo.toml, and op_picker/mod.rs
- Remove deleted READABILITY_AND_MODERNIZATION.md reference from
  codebase-readability.mdx
- Delete _iteration_log.md (git history is the archive)


* docs(roadmap): fix lychee false-positive link in move-contributing-testing

The example redirect text contained a markdown hyperlink to a proposed
future file path that doesn't exist yet. Changed to a code span.


---------

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>