docs: align verify commands with CI, fix doc drift, add architecture guides

[vkayonline]

What

This PR sets up proper in-repo contributor documentation and fixes existing doc drift:

• Canonicalizes the "verify before done" commands across TERAX.md, README.md, CONTRIBUTING.md, and the PR template to match what CI actually runs (.github/workflows/ci.yml).
• Fixes TERAX.md drift from the current codebase:
  • Adds missing providers: DeepSeek, Mistral, OpenRouter.
  • Adds fish shell integration details.
  • Adds missing command-palette/ and spaces/ modules.
• Removes the stale 0.5.x version pin in SECURITY.md.
• Replaces all em-dashes in markdown with hyphens/colons, per the no-em-dash convention.
• Adds a docs/ tree with long-form contributor guides:
  • docs/README.md - index
  • docs/architecture/two-process-model.md - IPC boundary and command reference
  • docs/architecture/pty-shell-integration.md - PTY, shell init, OSC, ConPTY, Job Object
  • docs/architecture/security-model.md - consolidated security boundaries
  • docs/architecture/ai-subsystem.md - AI stack + "Adding a provider" walkthrough
  • docs/architecture/terminal-renderer-pool.md - renderer pool and DormantRing invariants
  • docs/contributing/testing.md - testing contract and core-subsystem invariants

Why

The project already had a strong README.md, CONTRIBUTING.md, and TERAX.md, but:

• Verify commands were inconsistent across files and drifted from CI.
• TERAX.md had drifted from config.ts (providers), shell_init.rs (fish), and the actual module tree.
• There was no in-repo deep-dive documentation for contributors; docs/ only held screenshots.

How

• TERAX.md remains the source of truth. Each new guide starts with "If anything conflicts with TERAX.md, TERAX.md wins."
• New guides link back to TERAX.md and the docs/README.md index.
• Source snippets and claims were verified against the current code.

Testing

• pnpm check-types clean
• pnpm test - 245 tests passed; one pre-existing suite failure in src/app/eager-budget.test.ts (SyntaxError importing .mjs), unrelated to docs
• pnpm lint - passed with pre-existing warnings (biome does not lint .md)
• cargo clippy --all-targets --locked -- -D warnings - could not run; cargo is not installed in this environment
• cargo test --locked / cargo nextest run --locked - could not run; cargo is not installed in this environment
• Em-dash/en-dash scan in **/*.md returns zero matches
• Internal markdown links resolve

Notes for reviewer

• This is a docs-only change; no source code was modified.
• The .gitignore change adding .codegraph/ and the untracked opencode.json / .opencode/ files were left out of this PR because they are not part of the documentation work.

Summary by CodeRabbit

• Documentation
  • Expanded and reorganized contributor and architecture guides, including new guides for the testing workflow, security model, PTY shell integration, AI subsystem behavior, and the two-process model.
  • Updated verification instructions across README, contributing materials, and the architecture policy doc to use the latest lint/type-check/test commands and split/clarify Rust clippy vs. nextest guidance.
  • Refined repository policies and templates (SECURITY, Code of Conduct, PR template) with improved wording, punctuation consistency, and clearer reporting expectations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 80360d2d-980c-4e91-81b8-3da8724370c8

📥 Commits

Reviewing files that changed from the base of the PR and between 538f95d and 8942618.

📒 Files selected for processing (1)

• docs/architecture/ai-subsystem.md

✅ Files skipped from review due to trivial changes (1)

• docs/architecture/ai-subsystem.md

---

📝 Walkthrough

Walkthrough

Adds contributor docs and architecture references, updates root guidance to current lint/typecheck/test and Rust verification commands, and refreshes security/community wording. The new docs/ index centralizes links while the architecture pages expand PTY, security, AI, and renderer-pool documentation.

Changes

Contributor docs, architecture guides, and quality bar update

Layer / File(s)	Summary
Quality bar and check commands across root docs TERAX.md, CONTRIBUTING.md, README.md, .github/PULL_REQUEST_TEMPLATE.md	Canonical check commands are updated to pnpm lint, pnpm check-types, pnpm test, cargo clippy --all-targets --locked -- -D warnings, and cargo nextest run --locked with cargo test --locked as fallback. TERAX.md also adds the "Verify before claiming done" checklist and a core-change test requirement.
TERAX.md architecture expansion TERAX.md	Expands PTY/shell behavior, module layout, AI provider coverage, UI conventions, the Windows Enter rule, and adds a Further reading section.
docs/README.md navigation index docs/README.md	Creates a docs index with categorized links to TERAX.md, CONTRIBUTING.md, and the architecture/testing guides.
Two-process model and IPC catalog docs/architecture/two-process-model.md	Adds the Rust/webview boundary guide, IPC command-add checklist, and grouped command catalog.
PTY shell integration architecture docs/architecture/pty-shell-integration.md	Adds the PTY session model, shell bootstrapping details, ConPTY lifetime controls, input handling, and invariants.
Security model architecture docs/architecture/security-model.md	Adds trust boundaries, deny-list enforcement, workspace auth, AI tool approval, SSRF/DNS-rebinding defenses, secret storage, OSC gating, and invariants.
AI subsystem architecture docs/architecture/ai-subsystem.md	Adds BYOK/provider handling, runAgentStream, sub-agent rules, session persistence, composer context, tool approval flow, and live context bridging.
Terminal renderer pool architecture docs/architecture/terminal-renderer-pool.md	Adds slot lifecycle, parking/releasing rules, DormantRing, replay behavior, and WebGL addon lifecycle.
Testing contributing guide docs/contributing/testing.md	Adds local check commands, required test areas, PTY platform gating, security-path test coverage, and invariant guidance.
Community file normalization CODE_OF_CONDUCT.md, README.md, SECURITY.md	Normalizes dash punctuation and updates SECURITY.md reporting, version, and local LLM trust wording.

Estimated code review effort: 2 (Simple) | ~15 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title uses a Conventional Commits prefix and accurately summarizes the documentation-focused changes and added architecture guides.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/ai-subsystem.md`:
- Line 71: The mutating-tools approval list in the architecture docs includes a
stale shell tool name; update the list to match the current shell tool surface
by removing bash_session_run and keeping the shell-related entries aligned with
src/modules/ai/tools/shell.ts, especially the bash_run and bash_background tool
names referenced in the approval flow description.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 299fa4ee-fda7-4b5a-9592-3fe507777e2d

📥 Commits

Reviewing files that changed from the base of the PR and between 3d1ba19 and 4b77da7.

📒 Files selected for processing (13)

• .github/PULL_REQUEST_TEMPLATE.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• README.md
• SECURITY.md
• TERAX.md
• docs/README.md
• docs/architecture/ai-subsystem.md
• docs/architecture/pty-shell-integration.md
• docs/architecture/security-model.md
• docs/architecture/terminal-renderer-pool.md
• docs/architecture/two-process-model.md
• docs/contributing/testing.md

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/ai-subsystem.md`:
- Line 70: The read-only tools list is outdated and still references the old
grep/glob names. Update the documentation text in the architecture section to
use the current tool names `fs_search`, `fs_grep`, and `fs_glob` alongside
`read_file` and `list_directory`, so the tool list matches the actual APIs.

In `@docs/architecture/security-model.md`:
- Around line 44-48: Update the approval policy description in the security
model docs to match the current tool surface in src/modules/ai/tools/tools.ts.
Remove the stale read-only entries for grep and glob if they are no longer
exposed, and revalidate the mutating tools list against the actual tool
definitions so the documented needsApproval set matches the source of truth. Use
the tool names from tools.ts and keep the read-only vs mutating approval
behavior consistent with the implementation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 70db8c7b-b750-424f-937c-4bc1113a5e4b

📥 Commits

Reviewing files that changed from the base of the PR and between 4b77da7 and 538f95d.

📒 Files selected for processing (13)

• .github/PULL_REQUEST_TEMPLATE.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• README.md
• SECURITY.md
• TERAX.md
• docs/README.md
• docs/architecture/ai-subsystem.md
• docs/architecture/pty-shell-integration.md
• docs/architecture/security-model.md
• docs/architecture/terminal-renderer-pool.md
• docs/architecture/two-process-model.md
• docs/contributing/testing.md

✅ Files skipped from review due to trivial changes (9)

• docs/README.md
• docs/architecture/two-process-model.md
• .github/PULL_REQUEST_TEMPLATE.md
• SECURITY.md
• docs/architecture/pty-shell-integration.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• docs/architecture/terminal-renderer-pool.md
• TERAX.md

[crynta]

Thanks for this, really solid contribution. The provider list and CI-command drift were both real, and the new architecture docs are grounded in the actual code, not filler. Rebased on main and dropped a stale tool name CodeRabbit caught. Merged.