README.md

@@ -8,7 +8,7 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa
 
 | Path | What it holds |
 | --- | --- |
-| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, agents, hooks, MCP servers, and bundled assets |
+| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets |
 | `providers/claude-code/` | Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh` |
 | `core/` | Provider-agnostic always-on content — `core/AGENTS.md` and `core/instructions/` |
 | `docs/` | Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes |
@@ -18,7 +18,7 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa
 The six plugins:
 
 - **kyberforge** — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace
-- **git** — conventional commits, branch management, pull requests, feature flow
+- **git** — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running (`pc-author` / `pc-run`)
 - **gitea** — issues, pull requests, milestones, releases, wikis
 - **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it
 - **lint** — configuring and running linters
@@ -50,12 +50,12 @@ Run these in order, from the repo root.
 apm install
 
 # 2. Install the git hooks — all three stages
-#    (use the `pc-run` skill, which knows the stage wiring)
+pre-commit install -t pre-commit -t commit-msg -t pre-push
 ```
 
 **`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins/<name>/.apm/` remains the only place to edit. It needs the network, materializes `apm_modules/` (which stays gitignored), and also configures the `obsidian` MCP server into the repo's `.mcp.json`.
 
-**Git hooks** go in via the `pc-run` skill, wiring **all three stages**. This repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain `pre-commit install` silently skips `commit-msg` (Conventional Commits) and `pre-push` (the full gate).
+**Git hooks** must be wired for **all three stages**. This repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain `pre-commit install` silently skips `commit-msg` (Conventional Commits) and `pre-push` (the full gate) — the `-t` flags above are not optional. The `pc-run` skill handles this and the troubleshooting around it, if you would rather not remember the flags.
 
 ## Keeping the install current
 

docs/spec/architecture.md

@@ -29,13 +29,17 @@ Skills, agents, MCP servers, and hooks are distributed as self-contained plugin
 
 Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is `core` vs `kyberforge`: `core` is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against *their* repo, while `kyberforge` is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's `AGENTS.md` is `core`; a skill that audits a `SKILL.md` against this marketplace's contract is `kyberforge`.
 
+The second boundary worth stating is `git` vs `gitea`, because both own things called branches and both touch pull requests: `git` is whatever works over the git wire protocol against a local clone, `gitea` is whatever goes through the forge's HTTP API. That is why `git-branches` and `gitea-branches` both exist and are not duplicates.
+
+These are routing boundaries, not inventories — they answer "where does a new skill go", so they deliberately do not enumerate what each plugin ships today. For what a consumer actually gets, read the plugin's published `description` in its `apm.yml`.
+
 | Plugin | Scope |
 |---|---|
 | `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it |
-| `git` | Conventional commits, branch management, history, worktrees, remotes |
-| `gitea` | Issues, pull requests, labels, milestones, releases, wikis |
+| `git` | Git operations and git hook tooling — anything driven over the git wire protocol against a local clone, plus the pre-commit hooks that guard it |
+| `gitea` | Anything reached through the Gitea HTTP API rather than the git wire protocol — the forge's own objects |
 | `kyberforge` | Creating and maintaining a Claude Code / Copilot CLI plugin marketplace — this repo's own meta-tooling |
-| `lint` | Configuring and running linters; repo-agnostic, first linter is Vale (`vale-config` / `vale-run`, plus the `lint-runner` agent) |
+| `lint` | Configuring and running linters against a target repo; repo-agnostic, first linter is Vale |
 | `bin` | Unsorted skills that have not earned a home yet |
 
 Two compilers produce the plugin roots you see in the tree:

docs/spec/gates.md

@@ -27,7 +27,7 @@ stage including this one. Fourteen is the count of repo-defined pre-push hooks.
 
 ## The pre-push gate
 
-Fourteen hooks, in config order.
+Fourteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
 
 **Core checks**