docs: repair README and align layout, HITL resume, and process grouping

[cursor]

Overview

Repair the landing README and align public docs with the current episode layout, pause-on-veto approval path, and process grouping.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

The README mixed verification and resume examples into broken fences and still linked to removed docs/app/... paths. Several explanation pages still described nested label/ episode directories and ns.set(label=...) / ns.set(log_prompts=True), which are not config keys. HITL Slack/Gradio/async examples started a new episode after approval, which cannot continue a sealed run.

Docs added/updated

• Updated: README.md, docs/index.mdx, docs/quickstart.mdx, docs/explanation/artifacts.mdx, docs/explanation/core-concepts.mdx, docs/explanation/prompt-provenance.mdx, docs/guides/human-in-the-loop.mdx, docs/guides/configure-shared-storage.mdx, docs/reference/python-api.mdx, docs/docs.json, llms.txt, examples/README.md, noesis-tui/README.md
• Added: docs/reference/llms-txt.mdx

Codepaths they cover

• Layout: noesis/runtime/paths.py, noesis/infrastructure/layout.py, tests/runtime/test_episode_dir_layout.py
• IDs: noesis/state/episode.py (ep_<ULID>), noesis/runtime/artifacts/ids.py
• Process grouping: noesis/domain/process.py (derive_process_identity), noesis/__init__.py (process=), noesis/cli/__main__.py (--process, processes, runs)
• Config: noesis/domain/config/settings.py (ALLOWED_CONFIG_KEYS; no label / seed / log_prompts)
• HITL / pause-on-veto: noesis/usecases/run_lifecycle.py, tests/runtime/test_run_lifecycle.py
• Verification: noesis/verification.py, noesis/cli/verification_input.py
• Index: noesis/core.py (EpisodeIndex under layout.index_dir, ttl_days=30)

Key knowledge gaps addressed

• README was not copy-pasteable (broken fences, stale docs links, mixed verification/resume blocks)
• Docs still showed nested .noesis/episodes/<label>/ep_... and ns.set(label=...)
• NOESIS_RUNS_DIR=/srv/noesis/episodes does not keep that path as the episodes root unless the parent is named .noesis
• Approval examples called interrupt after a sealed run or started a follow-up ns.run instead of resume_run
• docs.json pointed at reference/llms-txt with no page; llms.txt listed unpublished/deprecated guides
• Existing first-episode / first-policy / incident-triage tutorials were not in the sidebar

Technical Details

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

Validation

Required

• Equivalent targeted suite: /tmp/noesis-docs-venv/bin/python -m pytest tests/domain/test_process_identity.py tests/runtime/test_episode_dir_layout.py tests/runtime/test_layout_paths.py tests/cli/test_process_commands.py tests/runtime/test_run_lifecycle.py -q (24 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 derive_process_identity, unknown label/log_prompts keys, and ep_<ULID> IDs

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/checkpoint (RunSealedError) and that paused runs must not have artifacts hand-edited.

Related Issues / References

• Layout: ADR-013 default .noesis/episodes (flat ep_<ULID> bundles)
• Pause-on-veto: tests/runtime/test_run_lifecycle.py
• Process identity: derive_process_identity(workspace|name)[:12]