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 docs, including new guides for testing, security, terminal integration, AI behavior, and the app’s two-process model.
  • Updated onboarding and quality-check instructions with current lint, type-check, test, and Rust verification steps.
  • Refined project policies and support guidance in the README, SECURITY, CONTRIBUTING, and Code of Conduct files.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds five new architecture docs (docs/architecture/) and a testing guide (docs/contributing/testing.md), plus a docs/README.md navigation index. Updates TERAX.md, CONTRIBUTING.md, README.md, and the PR template to replace old check commands with pnpm lint/check-types/test and cargo nextest/clippy -D warnings. Minor punctuation normalization across community files.

Changes

Contributor docs, architecture guides, and quality bar

Layer / File(s)	Summary
Quality bar and check commands TERAX.md, CONTRIBUTING.md, README.md, .github/PULL_REQUEST_TEMPLATE.md	Canonical check commands 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 fallback). TERAX.md adds a "Verify before claiming done" checklist and a test-invariant requirement for core subsystem changes. CONTRIBUTING.md gains project layout overhaul and references to docs/README.md.
TERAX.md architecture expansion TERAX.md	Expands PTY/shell init platform specifics, reorganizes frontend/module layout, updates AI subsystem provider list, adds UI convention details, cross-platform CR note, and a new Further reading section.
docs/README.md navigation index docs/README.md	New file with categorized links to TERAX.md, CONTRIBUTING.md, and all architecture/contributing guide pages.
Two-process model and IPC catalog docs/architecture/two-process-model.md	Full new doc: Rust/webview boundary rules, IPC command-addition checklist, and module-grouped command catalog (PTY, filesystem, git, shell, workspace, network/AI, secrets, agent hooks, history, settings).
PTY shell integration architecture docs/architecture/pty-shell-integration.md	New doc covering PtyState session model, Reader/Flusher/Waiter thread roles, shell bootstrapping on Unix and Windows (incl. ConPTY mutex, Job Object lifetime), input/escape handling, and invariants.
Security model architecture docs/architecture/security-model.md	New doc covering trust boundaries, path deny-list/canonicalization, workspace auth registry, AI tool approval flow, SSRF/DNS-rebinding defenses, secret storage, OSC trust gating, and invariants.
AI subsystem architecture docs/architecture/ai-subsystem.md	New doc covering BYOK provider handling, runAgentStream loop, sub-agent registry, session persistence, composer context, tool approval flow, ai-diff UX, and live context bridge.
Terminal renderer pool architecture docs/architecture/terminal-renderer-pool.md	New doc covering slot lifecycle, parking/releasing decision rules, DormantRing buffer, never-serialize-mid-command invariant, fast-path/snapshot replay, and WebGL addon lifecycle.
Testing contributing guide docs/contributing/testing.md	New doc: local CI-equivalent commands, test-required behavior areas, cross-platform PTY #[cfg] gating rules, security-path coverage requirements (symlink, NTFS ADS, deny-prefix), and invariant checklist.
Community file normalization CODE_OF_CONDUCT.md, README.md, SECURITY.md	Em-dash → hyphen normalization throughout; SECURITY.md adds response-timing note, no-public-issue instruction, version pointer redirected to package.json/Releases, and new local LLM trust-level bullet.

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	Uses Conventional Commits format and accurately summarizes the documentation and guide updates in the PR.
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]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n 'bash_run|bash_background|bash_session_run|run_command|shell_session_run|shell_bg_spawn' src/modules/ai/tools/

Repository: crynta/terax-ai

Length of output: 1600

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- src/modules/ai/tools/tools.ts ---'
sed -n '1,220p' src/modules/ai/tools/tools.ts

echo
echo '--- src/modules/ai/tools/shell.ts ---'
sed -n '1,220p' src/modules/ai/tools/shell.ts

echo
echo '--- docs/architecture/ai-subsystem.md (around line 71) ---'
sed -n '60,82p' docs/architecture/ai-subsystem.md

Repository: crynta/terax-ai

Length of output: 8476

---

Replace the stale shell-tool name in the approval list.
bash_session_run is not part of the current shell tool surface here; the mutating tools are bash_run and bash_background. Update the list so the approval flow matches src/modules/ai/tools/shell.ts.

🤖 Prompt for 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.

In `@docs/architecture/ai-subsystem.md` at 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.