ci: add agent docs structure linter with Setup section

.pre-commit-config.yaml

@@ -46,3 +46,9 @@ repos:
         language: system
         files: ^\.github/workflows/lint\.yml$
         pass_filenames: false
+      - id: lint-agent-docs
+        name: lint agent doc references and structure
+        entry: ./hack/lint-agent-docs
+        language: script
+        files: ^(harness/|docs/|hack/lint-agent-docs)
+        pass_filenames: false

Makefile

@@ -54,6 +54,7 @@ script-test:
 	$(call run-timed,bash scripts/post-scribe-test.sh)
 	$(call run-timed,bash scripts/validate-output-schema-test.sh)
 	$(call run-timed,bash scripts/gitlint-forbidden-type-scope-test.sh)
+	$(call run-timed,bash hack/lint-agent-docs-test.sh)
 	$(call run-timed,bash .github/scripts/check-e2e-authorization-test.sh)
 	$(call run-timed,bash .github/scripts/select-eval-agents-test.sh)
 	$(call run-timed,python3 scripts/process-fix-result-test.py)

docs/code.md

@@ -4,6 +4,10 @@
 
 Implementation specialist that reads triaged GitHub issues, implements fixes or features following repository conventions, runs tests and linters, and commits to a local feature branch.
 
+## Setup
+
+No additional setup is required beyond the standard fullsend configuration.
+
 ## How it helps
 
 - Triaged issues can go from "ready" to "PR open" without human involvement.

docs/fix.md

@@ -4,6 +4,10 @@
 
 Review-feedback specialist that reads review comments on open PRs, implements targeted fixes, runs tests and linters, and commits the result.
 
+## Setup
+
+No additional setup is required beyond the standard fullsend configuration.
+
 ## How it helps
 
 - Review feedback is addressed quickly — often before the reviewer checks back.
@@ -39,6 +43,58 @@ command. The text gives you direct control over what to fix:
 further automatic fix runs. Manual `/fs-fix` commands still work.
 Remove the label or use `/fs-fix` to re-engage.
 
+## Control labels
+
+| Label | Meaning |
+|-------|---------|
+| `fullsend-no-fix` | Prevents automatic fix runs on this PR. Applied by `/fs-fix-stop`. Manual `/fs-fix` commands are unaffected. |
+| `needs-human` | The fix agent is approaching its iteration cap and needs human direction. Applied automatically when an automatic fix iteration reaches the warning threshold. |
+
+## Configuration
+
+See [Customizing with AGENTS.md](https://fullsend.sh/docs/guides/user/customizing-with-agents-md) and
+[Customizing with Skills](https://fullsend.sh/docs/guides/user/customizing-with-skills).
+
+### Variables
+
+None.
+
+## How the agent works
+
+The fix agent follows a similar pipeline to the [code agent](code.md), with an additional validation step:
+
+1. **Pre-script** validates inputs and checks the iteration cap (preventing infinite fix loops).
+2. **Sandbox** — the agent reads each review finding, implements targeted fixes, and verifies them against tests and linters.
+3. **Validation loop** — the output is checked against a schema, with up to 2 retry iterations if the output is malformed.
+4. **Post-script** pushes the commit and posts a summary comment on the PR.
+
+### Input details
+
+**Bot-triggered** (review agent requests changes):
+
+| Input | Source | How it gets there |
+|-------|--------|-------------------|
+| Review body | Latest `CHANGES_REQUESTED` review from the review bot | Pre-fetched on the runner before the sandbox starts, injected as `review-body.txt` |
+| PR diff | `gh pr diff` inside the sandbox | Agent calls this to understand what code changed |
+| Repository checkout | Full repo at PR HEAD | Checked out on the runner, mounted into the sandbox |
+| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Read from the checkout inside the sandbox |
+
+**Human-triggered** (`/fs-fix [instruction]`):
+
+| Input | Source | How it gets there |
+|-------|--------|-------------------|
+| Human instruction | Free text after `/fs-fix` in the comment | Extracted by the workflow, passed as `HUMAN_INSTRUCTION` env var (up to 10,000 bytes) |
+| PR diff | `gh pr diff` inside the sandbox | Same as bot-triggered |
+| Repository checkout | Full repo at PR HEAD | Same as bot-triggered |
+| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Same as bot-triggered |
+| Review body (if any) | Prior review bot `CHANGES_REQUESTED` review | Still injected as `review-body.txt`, but human instruction takes precedence |
+
+## Custom sandbox image
+
+The fix agent shares the [code agent's sandbox image](code.md#custom-sandbox-image).
+If your project uses a custom image, update the `image:` field in both
+`harness/code.yaml` and `harness/fix.yaml`.
+
 ## What the agent acts on
 
 **When triggered by a review:** the agent reads the review body, the PR diff,
@@ -99,60 +155,6 @@ The fix agent enforces iteration caps to prevent infinite review-fix loops:
 - Each `/fs-fix` comment cancels any in-flight fix run for the same PR and
   starts a new one.
 
-## Control labels
-
-| Label | Meaning |
-|-------|---------|
-| `fullsend-no-fix` | Prevents automatic fix runs on this PR. Applied by `/fs-fix-stop`. Manual `/fs-fix` commands are unaffected. |
-| `needs-human` | The fix agent is approaching its iteration cap and needs human direction. Applied automatically when an automatic fix iteration reaches the warning threshold. |
-
-## Configuration
-
-See [Customizing with AGENTS.md](https://fullsend.sh/docs/guides/user/customizing-with-agents-md) and
-[Customizing with Skills](https://fullsend.sh/docs/guides/user/customizing-with-skills).
-
-### Variables
-
-None.
-
-## Custom sandbox image
-
-The fix agent shares the same sandbox image as the code agent. If your
-project requires tools not in the universal image, see
-[Custom sandbox image](code.md#custom-sandbox-image) in the code agent
-docs. Remember to update the `image` field in both `harness/code.yaml`
-and `harness/fix.yaml`.
-
-## How the agent works
-
-The fix agent follows a similar pipeline to the [code agent](code.md), with an additional validation step:
-
-1. **Pre-script** validates inputs and checks the iteration cap (preventing infinite fix loops).
-2. **Sandbox** — the agent reads each review finding, implements targeted fixes, and verifies them against tests and linters.
-3. **Validation loop** — the output is checked against a schema, with up to 2 retry iterations if the output is malformed.
-4. **Post-script** pushes the commit and posts a summary comment on the PR.
-
-### Input details
-
-**Bot-triggered** (review agent requests changes):
-
-| Input | Source | How it gets there |
-|-------|--------|-------------------|
-| Review body | Latest `CHANGES_REQUESTED` review from the review bot | Pre-fetched on the runner before the sandbox starts, injected as `review-body.txt` |
-| PR diff | `gh pr diff` inside the sandbox | Agent calls this to understand what code changed |
-| Repository checkout | Full repo at PR HEAD | Checked out on the runner, mounted into the sandbox |
-| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Read from the checkout inside the sandbox |
-
-**Human-triggered** (`/fs-fix [instruction]`):
-
-| Input | Source | How it gets there |
-|-------|--------|-------------------|
-| Human instruction | Free text after `/fs-fix` in the comment | Extracted by the workflow, passed as `HUMAN_INSTRUCTION` env var (up to 10,000 bytes) |
-| PR diff | `gh pr diff` inside the sandbox | Same as bot-triggered |
-| Repository checkout | Full repo at PR HEAD | Same as bot-triggered |
-| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Same as bot-triggered |
-| Review body (if any) | Prior review bot `CHANGES_REQUESTED` review | Still injected as `review-body.txt`, but human instruction takes precedence |
-
 ## Source
 
 [`harness/fix.yaml`](../harness/fix.yaml)

docs/prioritize.md

@@ -4,6 +4,10 @@
 
 Scores a GitHub issue using the RICE framework (Reach, Impact, Confidence, Effort) and produces scores with reasoning for project board ranking.
 
+## Setup
+
+No additional setup is required beyond the standard fullsend configuration.
+
 ## How it helps
 
 - Issues are ranked consistently using the same framework, reducing bias from whoever happens to see them first.

docs/retro.md

@@ -4,6 +4,10 @@
 
 Performs retrospectives on agent workflows — analyzes what happened, identifies improvement opportunities, and proposes changes as GitHub issues.
 
+## Setup
+
+No additional setup is required beyond the standard fullsend configuration.
+
 ## How it helps
 
 - Every workflow gets a post-mortem, not just the ones that failed badly enough for someone to notice.

docs/review.md

@@ -4,6 +4,10 @@
 
 Code review specialist that evaluates pull requests for correctness, security, intent alignment, style, and documentation currency.
 
+## Setup
+
+No additional setup is required beyond the standard fullsend configuration.
+
 ## How it helps
 
 - Every PR gets a thorough review within minutes, regardless of team availability.

docs/scribe.md

@@ -1,18 +1,70 @@
 # Scribe Agent
 
-Reads Google Drive meeting notes, maps discussion topics to the GitHub issue backlog, and adds comments to relevant issues or creates new issues.
+Reads meeting notes that Gemini saves to Google Drive after a
+Google Meet call, maps discussion topics to the GitHub issue
+backlog, and adds comments to relevant issues or creates new
+issues.
+
+## Setup
+
+If you want to give autonomous agents access to your meeting notes, you
+immediately face a trust problem: how do you prevent the agent from reading
+notes it shouldn't have access to and then happily exposing that information
+in public GitHub issues?
+
+The answer is a **dedicated GCP service account**. You create it in Google
+Cloud, and by default it has access to *zero* Drive files. You then
+**invite** the service account's email address to the Google Calendar events
+you want it to scribe. (In the calendar event settings you also need to
+enable Gemini notes and grant read access to attendees outside your
+organization.) In our experience, this calendar invite is how the resulting
+notes document becomes visible to the service account's Drive access — but
+the exact behavior may depend on your Workspace edition and admin policies
+(domain-wide delegation settings, external-guest sharing restrictions, etc.).
+Consult your Workspace admin if the service account cannot see expected
+notes.
+
+At runtime, the pre-script queries the Drive API using a keyword search
+(`SCRIBE_SEARCH_QUERY`) over a rolling time window (`SCRIBE_LOOKBACK_HOURS`,
+default 3 hours) across everything the service account can see — including
+Shared Drives if the account has been added to any. This means the service
+account can read notes from *any* meeting it has been invited to, not just a
+single event. To keep the blast radius small, use a distinctive search query
+and avoid adding the service account to unrelated Shared Drives.
+
+Scribe wakes up on a schedule, uses the service account credentials to
+search Drive for matching notes, and processes them: it files new GitHub
+issues on your repo or comments on existing ones, noting that the team
+discussed the topic in their meeting. This is an important bridge between
+the team's life of human interaction and the fullsend agentic system — the
+filed and commented-on issues serve as fodder for the triage agent, coding
+agent, and others.
 
 ## How it helps
 
-- Meeting decisions and action items reach the issue backlog without manual copy-paste.
-- Topics are matched to existing issues by title and body content, not just keywords.
-- Public-safety and PII gates prevent confidential meeting content from reaching GitHub.
-- Idempotency checks avoid duplicate comments when the same notes URL was already posted.
+- Meeting decisions and action items reach the issue backlog
+  without manual copy-paste.
+- Topics are matched to existing issues by title and body
+  content, not just keywords.
+- Public-safety and PII gates prevent confidential meeting
+  content from reaching GitHub.
+- Idempotency checks avoid duplicate comments when the same
+  notes URL was already posted.
 
 ## Triggers
 
 The scribe agent runs on a schedule or via manual trigger.
 
+## Commands
+
+The scribe agent does not accept slash commands.
+
+## Control labels
+
+Scribe does not consume or apply labels that gate agent behavior. It does
+apply a `meeting-notes` label (or agent-specified labels) to issues it
+creates, for categorization only.
+
 ## Configuration
 
 Register the agent in your `.fullsend` config (ADR 0058):
@@ -24,7 +76,7 @@ fullsend agent add \
   --fullsend-dir .
 ```
 
-### Environment variables
+### Variables
 
 Per ADR 0049, scribe configuration uses the `SCRIBE_` prefix.
 

docs/triage.md

@@ -4,6 +4,10 @@
 
 Inspects a GitHub issue, assesses information sufficiency, asks clarifying questions when needed, and produces a triage decision that determines whether the issue is ready for implementation.
 
+## Setup
+
+No additional setup is required beyond the standard fullsend configuration.
+
 ## How it helps
 
 - New issues get a response within minutes instead of waiting for a human to notice them.