docs: add user documentation structure and initial guides

README.md

@@ -36,6 +36,7 @@ This is not a product spec. It's an evolving exploration of a hard problem space
   - [Operational Observability](docs/problems/operational-observability.md) — How do the humans operating an autonomous software factory understand what it is doing, debug it when it goes wrong, and improve it over time?
 - **[docs/problems/applied/](docs/problems/applied/)** — Organization-specific considerations for downstream consumers:
   - [konflux-ci](docs/problems/applied/konflux-ci/) — Kubernetes-native CI/CD platform (the original proving ground)
+- **[docs/guides/](docs/guides/)** — Practical how-to documentation for administrators and developers (see [ADR 0023](docs/ADRs/0023-user-documentation-structure.md))
 - **[docs/ADRs/](docs/ADRs/)** — Architecture Decision Records for crystallizing specific decisions (see [ADR 0001](docs/ADRs/0001-use-adrs-for-decision-making.md))
 - **[web/](web/)** — Browser-delivered assets for the public site (document graph today; future Vite app here). Cloudflare Worker config lives in [`cloudflare_site/`](cloudflare_site/) ([ADR 0019](docs/ADRs/0019-web-source-and-cloudflare-site-layout.md)).
 - **[docs/landscape.md](docs/landscape.md)** — Survey of AI code review tools, orchestration patterns, and connectivity gateways; how they relate to our goals (time-sensitive — check the date)

docs/ADRs/0023-user-documentation-structure.md

@@ -0,0 +1,94 @@
+---
+title: "23. User documentation structure"
+status: Accepted
+relates_to:
+  - governance
+  - human-factors
+topics:
+  - documentation
+---
+
+# 23. User documentation structure
+
+Date: 2026-04-22
+
+## Status
+
+Accepted
+
+## Context
+
+Fullsend's existing documentation serves contributors and decision-makers: problem documents explore design space, ADRs record decisions, and normative specs define contracts. None of it is aimed at the two audiences who need operational guidance:
+
+1. **Administrators** — people who install fullsend in a GitHub org, configure agents, manage credentials, and enroll repositories.
+2. **Users** — developers who work in repositories where fullsend is active and need to understand how to interact with it.
+
+As adoption grows, this gap becomes a blocker. New admins have to reverse-engineer the install flow from Go source and normative specs. New developers have no documentation explaining what triggers agents, what to expect from agent-generated PRs, or how to intervene when something goes wrong.
+
+The question is how to structure user-facing documentation so it stays organized as the guide count grows.
+
+## Options
+
+### Option A: Audience-based split
+
+Two directories under `docs/guides/`:
+
+- `docs/guides/admin/` — guides for org administrators
+- `docs/guides/user/` — guides for developers in enrolled repos
+
+Each guide is a standalone how-to document focused on one task. Guides link to ADRs and `docs/architecture.md` for deeper context but never require reading those to complete the task.
+
+**Trade-offs:** Clear audience separation makes it obvious who a doc is for. Scales naturally as guides are added. Requires maintaining an index.
+
+### Option B: Single flat directory
+
+All guides in `docs/guides/` with naming conventions (e.g. `admin-installing-fullsend.md`, `user-bugfix-workflow.md`).
+
+**Trade-offs:** Simpler initially, but the audience split becomes invisible as the guide count grows. Naming conventions are easy to forget.
+
+## Decision
+
+Adopt **Option A: audience-based split** with the following structure and writing rules.
+
+### Directory structure
+
+```
+docs/guides/
+├── README.md           # Index linking both sections
+├── admin/              # Guides for org administrators
+│   └── installing-fullsend.md
+└── user/               # Guides for developers
+    └── bugfix-workflow.md
+```
+
+### Writing rules
+
+1. **One audience, one task.** Each guide targets one audience (admin or user) and walks through one task.
+2. **Prerequisites first.** State what the reader needs before they start.
+3. **Steps, not prose.** Use numbered steps for procedures. Show the command, then explain what it does — not the reverse.
+4. **Link, don't restate.** Reference ADRs, normative specs, and `docs/architecture.md` for architectural context. Do not duplicate their content.
+5. **Mark planned features.** Features that do not exist yet use a `> **Planned**` callout that references the tracking issue.
+6. **No jargon without definition.** If a term has a specific meaning in fullsend, link to `docs/glossary.md` or define it inline on first use.
+
+### Anticipated admin topics
+
+- Installing fullsend (initial)
+- Adding, removing, or disabling agents
+- Configuring agent behavior
+- Setting up external compute
+- Connecting multiple independent fullsend installations for cross-instance flow
+
+### Anticipated user topics
+
+- Bugfix workflow (triage → code → review → merge)
+- Issue prioritization and backlog management
+- Feature discovery and refinement
+- Architecture drift management
+- Automated threat modelling and red-teaming
+
+## Consequences
+
+- Admins and users each have a clear place to look for guidance, separate from the design-oriented problem documents and normative specs.
+- New guides follow a consistent structure enforced by the writing rules, reducing maintenance burden.
+- The audience split must be maintained as new guides are added; the `docs/guides/README.md` index is the enforcement point.
+- Existing design documents (`docs/problems/`, `docs/ADRs/`, `docs/architecture.md`) remain unchanged — guides link into them, not the other way around.

docs/guides/README.md

@@ -0,0 +1,17 @@
+# Guides
+
+Practical how-to documentation for fullsend, organized by audience. For design documents and architectural context, see [docs/problems/](../problems/), [docs/ADRs/](../ADRs/), and [docs/architecture.md](../architecture.md).
+
+Structure decided in [ADR 0023](../ADRs/0023-user-documentation-structure.md).
+
+## Administration
+
+Guides for org administrators who install, configure, and manage fullsend.
+
+- [Installing fullsend](admin/installation.md) — Set up fullsend in a GitHub organization from scratch (see [#328](https://github.com/fullsend-ai/fullsend/pull/328))
+
+## User guides
+
+Guides for developers working in repositories where fullsend is active.
+
+- [Bugfix workflow](user/bugfix-workflow.md) — End-to-end guide to how fullsend handles a bug report from issue to merge

docs/guides/user/bugfix-workflow.md

@@ -0,0 +1,165 @@
+# Bugfix workflow
+
+How fullsend handles a bug report from issue creation to merged fix, end to end. This guide is for developers working in a repo where fullsend is [installed and enrolled](../admin/installation.md).
+
+## Overview
+
+When someone files a bug, fullsend's agent pipeline processes it through three stages:
+
+1. **Triage** — validates the issue, checks for duplicates, attempts reproduction
+2. **Code** — implements a fix, writes tests, opens a PR, passes CI
+3. **Review** — multiple review agents evaluate the PR independently, a coordinator decides the outcome
+
+Each stage is triggered by labels and can be restarted with slash commands. The pipeline uses GitHub's native primitives (issues, PRs, labels, branch protection) as its coordination layer — there is no central orchestrator. See [ADR 0002](../../ADRs/0002-initial-fullsend-design.md) for the full design.
+
+```
+Issue filed → Triage → ready-to-code → Code Agent → ready-for-review → Review → ready-for-merge → Merge
+                │                          ↑                              │
+                │                          └──────── changes requested ───┘
+                ├── duplicate → closed
+                ├── not-ready → waiting for info
+                └── not-reproducible → human intervention
+```
+
+## What you need to know as a developer
+
+### Writing good bug reports
+
+The triage agent reads **only** the issue title, body, and GitHub-native attachments. It does not read comments. This means:
+
+- Put all relevant information in the issue body — expected behavior, actual behavior, steps to reproduce, version/environment.
+- Use GitHub's native file attachments for logs, screenshots, or reproduction scripts.
+- If you need to update the report, **edit the issue body**, don't add a comment. Edits to the title or body trigger triage automatically.
+
+### Labels are the state machine
+
+These labels track where an issue is in the pipeline:
+
+| Label | Meaning | What happens next |
+|-------|---------|-------------------|
+| `duplicate` | Same issue already tracked elsewhere | Issue closed, link to canonical issue |
+| `not-ready` | Missing information | Triage comment explains what's needed; edit the issue body to fix |
+| `not-reproducible` | Bug couldn't be reproduced in the sandbox | Human intervention required; triage comment documents what was tried |
+| `ready-to-code` | Triage passed | Code agent picks it up |
+| `ready-for-review` | PR with passing CI ready for review | Review agents evaluate the PR |
+| `ready-for-merge` | All reviewers unanimously approved | PR can be merged per governance policy |
+| `requires-manual-review` | Reviewers disagreed or flagged security concerns | Human must decide |
+
+Labels are mutually exclusive where it matters — the pipeline enforces this. You generally don't need to manage labels manually.
+
+### Slash commands
+
+You can control the pipeline from issue or PR comments:
+
+| Command | Where | Effect |
+|---------|-------|--------|
+| `/triage` | Issue comment | Re-runs triage from scratch (clears all labels, reopens if closed) |
+| `/implement` | Issue comment | Hands off to the code agent (expects `ready-to-code` or forces with human ack) |
+| `/review` | PR comment | Enqueues a new review round for the current PR head |
+
+### What to expect from agent PRs
+
+When the code agent opens a PR:
+
+- The PR links back to the originating issue.
+- The PR description summarizes what was changed and why.
+- The code agent has already run the test suite in its sandbox and iterated until tests pass.
+- After pushing, GitHub's required checks run. If checks fail, the code agent fetches logs, fixes the issue, and pushes again (up to a configurable retry cap).
+- Once checks are green, the PR is labeled `ready-for-review` and the review agents take over.
+
+### Reviewing agent output
+
+Agent PRs go through the same review process as human PRs:
+
+- **CODEOWNERS still applies.** If your repo has CODEOWNERS rules, the required human reviewers must still approve — agents cannot bypass this.
+- **Branch protection still applies.** Required checks, review counts, and merge restrictions are unchanged.
+- **Read the diff.** Agent code is functional but may not match your team's style preferences. Treat it like any other PR.
+
+### Review outcomes
+
+The review stage runs N independent review agents in parallel. One is randomly selected as coordinator. The coordinator collects verdicts and applies one of three outcomes:
+
+- **Unanimous approve:** All reviewers agree the PR is good. Label `ready-for-merge` is applied. The PR can be merged per your org's governance policy.
+- **Unanimous rework:** All reviewers agree changes are needed. Label `ready-to-code` is re-applied and the code agent resumes work.
+- **Split or conflicting:** Reviewers disagree, or there are conflicting security assessments. Label `requires-manual-review` is applied. A human must decide.
+
+Every push to a PR in the review stage triggers a new review round. This means `ready-for-merge` is never stale — it always reflects the current PR head.
+
+> **Planned:** The **fix agent** ([#197](https://github.com/fullsend-ai/fullsend/issues/197)) will handle the rework loop automatically. When a review agent requests changes or a human posts `/fix-agent [instruction]`, the fix agent reads the review feedback and pushes fixes to the existing PR — no manual coding required. The fix agent is a separate workflow from the code agent, with its own prompt scoped to "read review feedback, fix existing PR."
+
+## The stages in detail
+
+### Stage 1: Triage
+
+**Triggered by:** issue creation, issue title/body edit, or `/triage` command.
+
+The triage agent:
+
+1. **Checks for duplicates.** Searches existing issues by title, body, and metadata. If it finds a match with high confidence, it labels `duplicate`, posts a comment linking the canonical issue, and closes this one.
+2. **Checks information sufficiency.** If the issue body is missing steps to reproduce, expected behavior, or other critical details, it labels `not-ready` and posts a comment explaining what's missing.
+3. **Attempts reproduction.** Runs the reported steps in an isolated sandbox. If the bug cannot be reproduced, it labels `not-reproducible` and posts a detailed comment documenting what was tried.
+4. **Produces a test artifact.** When possible, writes a failing test case aligned with the repo's test framework.
+5. **Hands off.** Labels `ready-to-code` with a summary comment.
+
+**If triage gets it wrong:** Edit the issue body with better information and triage re-runs automatically. Or use `/triage` to force a fresh run — this clears all previous labels and starts from scratch.
+
+### Stage 2: Code
+
+**Triggered by:** `ready-to-code` label or `/implement` command.
+
+The code agent:
+
+1. **Reads the handoff.** Issue title, body, attachments, and triage output comments.
+2. **Branches and implements.** Creates a branch, writes the fix following repo conventions.
+3. **Tests iteratively.** Runs the test suite, incorporates triage-provided tests if present, writes new tests if needed. Iterates until tests pass.
+4. **Opens a PR.** Links the issue, describes the changes.
+5. **Handles CI failures.** Fetches failing check logs, fixes issues, pushes again. Repeats until all required checks pass (up to a configurable cap, default defined in `config.yaml` as `defaults.max_implementation_retries`).
+6. **Hands off to review.** Labels `ready-for-review`.
+
+### Stage 3: Review
+
+**Triggered by:** `ready-for-review` label, `/review` command, or push to the PR branch.
+
+The review swarm:
+
+1. **N independent reviewers** evaluate the PR in parallel (configurable count).
+2. **One coordinator** (randomly selected) collects verdicts and posts a consolidated comment.
+3. **Outcome** is applied as a label: `ready-for-merge`, `ready-to-code` (rework), or `requires-manual-review`.
+
+Re-review happens automatically on every push to the PR. The `ready-for-merge` label is scoped to the PR head SHA at the time of review — it is cleared and re-evaluated on each new round.
+
+### After merge
+
+Once the PR is merged (by human, merge queue, or automation per org governance), the automated pipeline for this issue is complete.
+
+> **Planned:** The **retro agent** ([#131](https://github.com/fullsend-ai/fullsend/issues/131)) will capture lessons learned from the pipeline run — review rejections, CI failures, manual interventions — and feed them back into the agent harness configuration. This lets the system improve over time without manual prompt tuning. Feedback is scoped per-repo, with optional org-wide promotion, and maintainers can review corrections before they take effect.
+
+## Intervening in the pipeline
+
+### Stopping automation
+
+- Remove the triggering label. Without `ready-to-code` or `ready-for-review`, the next stage won't fire.
+- Close the issue. Agents don't act on closed issues (except `/triage` which explicitly reopens).
+
+### Restarting a stage
+
+- `/triage` — wipes all labels, reopens the issue, runs triage fresh.
+- `/implement` — restarts the code agent from the current issue state.
+- `/review` — enqueues a new review round.
+
+### Taking over manually
+
+At any point you can:
+
+1. Push commits to the agent's PR branch — the review agents will re-review.
+2. Close the agent's PR and open your own — the issue labels are your entry point.
+3. Remove the `ready-to-code` label to prevent the code agent from starting, then implement the fix yourself.
+
+Fullsend does not lock you out. The labels are the state machine, and you have full control over them.
+
+## Reference
+
+- [ADR 0002](../../ADRs/0002-initial-fullsend-design.md) — initial fullsend design (full workflow specification)
+- [Architecture overview](../../architecture.md) — component vocabulary and execution stack
+- [Installing fullsend](../admin/installation.md) — prerequisite: admin setup guide
+- [Security threat model](../../problems/security-threat-model.md) — how fullsend thinks about security

skills/writing-user-docs/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: writing-user-docs
+description: >-
+  Use when writing, editing, or adding user-facing documentation under
+  docs/guides/. Use when creating admin guides (install, configure, manage) or
+  user guides (workflows, interactions, interventions) for fullsend.
+---
+
+# Writing User Documentation
+
+## Overview
+
+User docs are task-oriented guides for two audiences: **administrators** who
+install and manage fullsend, and **developers** who work in enrolled repos.
+Structure and rules are decided in
+[ADR 0023](docs/ADRs/0023-user-documentation-structure.md).
+
+## Directory Layout
+
+```
+docs/guides/
+├── README.md              # Index — update when adding guides
+├── admin/                 # Org administrators
+│   └── installing-fullsend.md
+└── user/                  # Developers in enrolled repos
+    └── bugfix-workflow.md
+```
+
+## Writing Rules
+
+1. **One audience, one task.** Each guide targets admin or user, not both.
+2. **Prerequisites first.** State what the reader needs before step 1.
+3. **Steps, not prose.** Numbered steps for procedures. Command first, then
+   explain — not the reverse.
+4. **Link, don't restate.** Point to ADRs, normative specs, and
+   `docs/architecture.md` for architectural context.
+5. **Mark planned features.** Use a blockquote callout referencing the issue:
+
+   ```markdown
+   > **Planned:** The **fix agent** ([#197](...)) will handle ...
+   ```
+
+6. **No jargon without definition.** Link to `docs/glossary.md` or define
+   inline on first use.
+
+## Effective Writing
+
+Use the **elements-of-style:writing-clearly-and-concisely** skill when
+drafting or editing guides. Key principles:
+
+- Active voice, positive form, concrete language
+- Omit needless words — every sentence should earn its place
+- Parallel structure in lists and steps
+
+## Checklist
+
+- [ ] File is in the correct directory (`admin/` or `user/`)
+- [ ] Prerequisites section exists and is complete
+- [ ] Procedures use numbered steps
+- [ ] Commands appear before their explanations
+- [ ] Planned features use `> **Planned:**` callouts with issue links
+- [ ] All internal links resolve (ADRs, specs, other guides)
+- [ ] `docs/guides/README.md` index is updated
+- [ ] `make lint` passes
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Mixing admin and user content | Split into two guides |
+| Explaining architecture inline | Link to `docs/architecture.md` |
+| Documenting planned features as current | Add `> **Planned:**` callout |
+| Forgetting to update the index | Edit `docs/guides/README.md` |
+| Prose paragraphs for procedures | Convert to numbered steps |