docs: align incident triage, layout migration, and planner vs governance

[cursor]

🧠 Noēsis Pull Request

Overview

Keep public docs aligned with the current runtime: incident approval continues a paused episode, layout migration is a copy-not-move CLI, and planner_mode is not a governance switch.

Type of Change

• 📚 Documentation or research notes

Docs added/updated

• Updated: docs/tutorials/incident-triage.mdx, docs/tutorials/first-policy.mdx, docs/guides/write-policies.mdx, docs/guides/configure-planner-modes.mdx, docs/guides/configure-shared-storage.mdx, docs/reference/cli.mdx, docs/reference/configuration.mdx, docs/quickstart.mdx, docs/docs.json, llms.txt
• Added: docs/reference/llms-txt.mdx (nav already pointed at a missing page)

Codepaths they cover

• Pause-on-veto / resume: noesis/usecases/episode_runner.py (_build_snapshot), noesis/usecases/run_lifecycle.py, tests/runtime/test_run_lifecycle.py
• Built-in pre-act rules: noesis/domain/faculties/governance.py (rules.veto.danger, rules.veto.protected, rules.audit.sensitive)
• Public continuation APIs: noesis/__init__.py (run, resume_run, process=), noesis.io.paths
• Layout / migration: noesis/runtime/paths.py, noesis/infrastructure/layout_migration.py, tests/runtime/test_episode_dir_layout.py, tests/infrastructure/test_layout_migration.py
• Config keys: noesis/domain/config/settings.py (ALLOWED_CONFIG_KEYS)
• Shipped CLI: noesis/cli/__main__.py (run, --planner, migrate-layout; no --intuition / --policy)

Key knowledge gaps addressed

• Incident triage still started a new ns.run (and Gradio) after a sealed episode instead of governance_pause_on_veto + resume_run
• Docs treated planner_mode="minimal" as “skips governance”; enforce + pause-on-veto still runs PreActGovernor
• noesis run --intuition module:Class is not a shipped flag
• noesis migrate-layout was a one-liner with no copy/skip/ep_*-only constraints
• NOESIS_RUNS_DIR=/srv/noesis/episodes does not keep that path as the episodes root unless the parent is .noesis
• Quickstart still described episodes/_episodes/; index is .noesis/index/ (ttl_days=30)
• docs.json listed reference/llms-txt with no page; root llms.txt linked unpublished/deprecated pages
• Existing first-episode / first-policy / incident-triage tutorials were missing from the sidebar

Motivation & Context

Weekly docs automation. These pages were still teaching follow-up episodes for HITL and mixing planner vs governance, which fights the current lifecycle contract.

Technical Details

Documentation-only. No runtime, schema, or KPI changes.

Validation

Required

• Equivalent targeted suite: /tmp/noesis-docs-venv/bin/python -m pytest tests/runtime/test_run_lifecycle.py tests/runtime/test_episode_dir_layout.py tests/runtime/test_layout_paths.py tests/infrastructure/test_layout_migration.py tests/governance/test_pre_act.py tests/domain/test_process_identity.py tests/cli/test_process_commands.py -q (32 passed)
• Schema validation and export diff clean — no schema edits; docs/docs.json parses

Situational

• Docs build: npx --yes mintlify@latest broken-links from docs/ — no broken links
• git diff --check; fenced-code blocks balanced; PYTHONPATH=. smoke for unknown label/log_prompts keys and derive_process_identity(workspace_identity=..., process_name=...)

ADR-003 Schema Governance Checklist

Not applicable (no schema/KPI changes).

Observability & Safety

No telemetry or behavior changes. Approval docs now warn that sealed runs reject interrupt/resume (RunSealedError) and that resume_run does not bypass PreActGovernor.

Related Issues / References

• Pause-on-veto: tests/runtime/test_run_lifecycle.py::test_governance_pause_mode_emits_interrupt_checkpoint_and_halts_side_effects
• Layout: ADR-013 default .noesis/episodes (flat ep_<ULID> bundles)
• Example UI still on legacy ns.run_using: examples/incident_triage/