docs: document configuration architecture and usage

docs/agents.md

@@ -0,0 +1,11 @@
+# Agents
+
+The five shared agents are logical roles, not mandatory steps.
+
+- `implementer` executes the smallest complete engineering change and performs self-review.
+- `researcher` investigates code, patterns, evidence, alternatives, and unknowns without modifying implementation code by default.
+- `architect` evaluates technical boundaries, dependencies, interfaces, constraints, and design options.
+- `verifier` checks completed work against requested behavior, acceptance criteria, tests, generated output, and configuration.
+- `reviewer` independently checks correctness, regressions, security, maintainability, architecture, tests, and unnecessary complexity.
+
+Use only the roles that are likely to improve the outcome. Choose `researcher`, `reviewer`, and `verifier` based on the task's uncertainty, complexity, risk, blast radius, and verification value; none runs automatically. The agent may make evidence-based, reversible technical decisions. Ask the user when technical choices remain materially uncertain or when business behavior, user-visible behavior, UI, UX, APIs, database models, configuration formats, compatibility behavior, or other high-impact decisions are ambiguous or open to interpretation.

docs/architecture.md

@@ -0,0 +1,5 @@
+# Architecture
+
+Shared Markdown and metadata define meaning once. Codex and Claude adapters contain only client-specific paths, filenames, and serialization details. The build script renders those inputs into `generated/`. Installation is a separate, explicit step that copies generated files into global user-level locations with backups.
+
+Generated output is ignored because it is reproducible build output. The source files are the reviewable record.

docs/configuration.md

@@ -0,0 +1,9 @@
+# Configuration
+
+Codex receives a generated global `AGENTS.md`, agent TOML files, skills, and a `config.toml` adapter with workspace sandboxing, interactive approval boundaries, automatic approval review, enabled sub-agents, and a five-thread concurrency limit. Claude Code receives a generated global `CLAUDE.md`, agent Markdown files, skills, and `settings.json` with the `auto` permission mode, explicit `Agent` permission, and a five-operation tool/sub-agent concurrency limit. The exact installed locations are resolved from the user profile at install time; no machine-specific absolute path is stored in the repository.
+
+Neither current client configuration model exposes a supported global `max_depth` setting. The repository does not emit an unsupported key that would be ignored or cause configuration validation errors.
+
+Client settings remain thin adapters. Shared semantics remain in `shared/`.
+
+User plugins are managed separately through `adapters/plugins.tsv` and the client-native plugin commands. They are not copied into `generated/` because each client owns its plugin cache and authentication state.

docs/hooks.md

@@ -0,0 +1,7 @@
+# Hooks
+
+Deterministic safety and validation hooks live in `shared/hooks/scripts/`. The flashbang entry points live directly in `shared/hooks/`. The command safety hook rejects obvious destructive commands outside the current development workspace. The session validation hook checks repository-local generated inputs. The post-change hook is an optional verification entry point.
+
+The build includes the hooks and their client-specific registration in each payload. Installation places them beside the generated client files. The scripts do not grant permissions, bypass approvals, or replace client permission systems.
+
+The PowerShell and Bash hook variants are registered only for the Codex and Claude `Stop` events. They run after the main agent finishes responding, not during tool calls, thinking, permission requests, or notifications. The default flash lasts about 500 milliseconds. The Windows command deliberately omits `-WindowStyle Hidden`, which can hide or minimize the shared terminal. The PowerShell hook creates a low-opacity click-through overlay without activating another window. The Bash hook creates the equivalent temporary overlay through Python's standard `tkinter` module, uses `xrandr` for multi-monitor bounds when available, and does not reactivate the terminal. It falls back to `notify-send` in headless or minimal environments. Hooks are intentionally not executed during build or doctor.

docs/plugins.md

@@ -0,0 +1,11 @@
+# Plugins
+
+The user-level plugin manifest is `adapters/plugins.tsv`. It maps each logical plugin to the marketplace selector understood by Claude Code and Codex.
+
+The current baseline includes Ponytail, i-have-adhd, Superpowers, and Context7. The install script operates at user scope and is idempotent: existing Claude plugins are enabled and updated, and Codex plugins are updated or ensured through the Codex plugin command.
+
+Plugin installation requires the corresponding client CLI, network access, and any authentication required by the plugin. Context7 may open an OAuth flow. Codex or plugin hooks may require a trust review in `/hooks`. The scripts never install plugins during a build or doctor run and never install them when `--dry-run` or `-DryRun` is used.
+
+If Codex reports that a marketplace is already registered from another source, the scripts remove only the conflicting marketplace name from the configured user-level Codex sources, add the repository source from the manifest, and continue with the Codex plugin command. Other marketplace errors remain fatal.
+
+Only trusted upstream marketplace sources should be added. Plugins are executable extensions and may access the permissions granted to their client.

docs/skills.md

@@ -0,0 +1,15 @@
+# Skills
+
+Skills are reusable workflows. Rules are persistent constraints and agents are specialized roles. Each skill is a minimal `SKILL.md` with YAML frontmatter and a small initial workflow so both clients can consume it.
+
+The current structure is organized by purpose:
+
+- `debugging/`
+- `planning/`: implementation planning, impact analysis, and work-item definition
+- `research/`: technical and repository research
+- `reviews/`: code, security, performance, WPF, UI/UX, business, API, and EF Core reviews
+- `implementation/`: SQL, unit-test, and integration-test writing
+- `verification/`: facts, work-item, and regression verification
+- `git/`: pull request responses and reviews
+
+The files intentionally define only a small baseline. Detailed personal workflows and standards can be added later without changing the structure.