webrenew · charlesrhoward · May 18, 2026 · May 18, 2026
diff --git a/content/docs/capabilities/agents.mdx b/content/docs/capabilities/agents.mdx
@@ -0,0 +1,89 @@
+---
+title: Agents
+description: Define reusable Mogplex agents with names, slugs, prompts, models, categories, skills, rules, and context.
+---
+
+Agents are reusable workers.
+
+Define them once in the app, then bind them to Triggers, Assignments,
+Automations, CLI work, or mention routing.
+
+## What an agent defines
+
+| Part | Why it matters |
+| --- | --- |
+| Name and description | Human-readable identity in pickers and lists |
+| Slug | Durable mention handle for `@mogplex/<slug>` routing |
+| Category | Roster organization and hygiene |
+| Model | The default model for that agent, constrained by the account catalog |
+| System prompt | The core behavior the agent should follow |
+| Skills | Reusable procedures, tools, prompts, and workflows |
+| Rules | Shared instruction blocks and policy constraints |
+| Context | Reusable memory and background knowledge |
+
+The roster can include built-in presets, owned custom agents, and forks of
+presets you have customized.
+
+## When to create or fork an agent
+
+Create or fork an agent when the behavior should be reused across more than one
+run, repo, or route.
+
+Good examples:
+
+- PR reviewer
+- issue triage assistant
+- CI failure investigator
+- frontend implementation agent
+- docs maintainer
+- release checklist runner
+
+If the behavior only changes one step inside one workflow, use an Automation
+node override instead of creating a separate agent.
+
+## Slugs and mentions
+
+For GitHub mentions, the slug is the routing identity.
+
+```text
+@mogplex
+@mogplex/triage
+@mogplex/frontend-review
+```
+
+Bare `@mogplex` routes only to the default mention route. Targeted
+`@mogplex/<slug>` mentions route to the agent slug configured on the trigger or
+automation entry path.
+
+Keep slugs short, lowercase, and obvious from the job.
+
+## Model hygiene
+
+Agent models are constrained by the live account model catalog.
+
+If an agent was created before a model was hidden, disabled, or renamed, the
+agent can still exist on that older model. When you edit long-lived agents,
+check [Available Models](/web/models) and move them to a visible enabled model
+when appropriate.
+
+## How agents connect to routing
+
+- [Triggers](/web/triggers) wake one agent from one GitHub event.
+- [Assignments](/web/assignments) bind one repo, one agent, and one standing
+  work type.
+- [Automations](/web/automations) orchestrate one or more agent nodes in a
+  workflow graph.
+- [Headless Runs](/platform/headless-runs) can start work from scripts and CI.
+- [Mogplex CLI](/platform/cli) can supervise local runs with model, approval,
+  diff, memory, and MCP controls.
+
+## Read next
+
+<Cards>
+  <Card title="Agent Authoring" href="/configure-and-extend/agent-authoring" />
+  <Card title="Agents Overview" href="/web/agents" />
+  <Card title="Roster and Slugs" href="/web/agents/roster-and-slugs" />
+  <Card title="Skills, Rules, and Context" href="/web/agents/skills-rules-context" />
+  <Card title="Model Selection and Cost" href="/guides/model-selection-and-cost" />
+  <Card title="Routing" href="/capabilities/routing" />
+</Cards>
diff --git a/content/docs/capabilities/index.mdx b/content/docs/capabilities/index.mdx
@@ -0,0 +1,74 @@
+---
+title: Capabilities
+description: "Learn the main Mogplex capabilities: agents, automations, triggers, assignments, observability, and reusable agent context."
+---
+
+Capabilities are the jobs Mogplex performs for a team. Use this section when
+you already know the kind of work you want and need the right product surface.
+
+<Cards>
+  <Card
+    title="Agents"
+    href="/capabilities/agents"
+    description="Reusable workers with names, slugs, prompts, models, categories, skills, rules, and context."
+  />
+  <Card
+    title="Agent Authoring"
+    href="/configure-and-extend/agent-authoring"
+    description="Design reusable agent contracts before binding them to routes, mentions, CLI workflows, or API runs."
+  />
+  <Card
+    title="Routing"
+    href="/capabilities/routing"
+    description="Choose between Triggers, Assignments, Automations, GitHub mentions, headless runs, and CLI execution."
+  />
+  <Card
+    title="GitHub Routing Cookbook"
+    href="/guides/github-routing-cookbook"
+    description="Concrete recipes for mentions, PR review, issue triage, CI failure response, scheduled work, and direct starts."
+  />
+  <Card
+    title="Review and Triage"
+    href="/capabilities/review-and-triage"
+    description="Configure pull request review, issue triage, CI failure investigation, mentions, and follow-up edits."
+  />
+  <Card
+    title="Observability"
+    href="/capabilities/observability"
+    description="Inspect run health, pressure, model calls, tool calls, tokens, cost, sandbox linkage, and runtime errors."
+  />
+  <Card
+    title="Automations"
+    href="/web/automations"
+    description="Deep dive on multi-step GitHub-triggered workflows with branches, delays, drafts, and publishing."
+  />
+  <Card
+    title="Skills, Rules, and Context"
+    href="/web/agents/skills-rules-context"
+    description="Reusable agent instructions and context that shape how agents behave across repos and runs."
+  />
+</Cards>
+
+## Choosing a capability
+
+If the work is a reusable worker, start with [Agents](/capabilities/agents). If
+the work is about deciding what should run, start with
+[Routing](/capabilities/routing). If the work is PR review, issue triage, CI
+failure response, or GitHub mentions, start with
+[Review and Triage](/capabilities/review-and-triage).
+
+Use [Observability](/capabilities/observability) after work starts, not before
+the account and repo setup are healthy.
+
+Use [Model Selection and Cost](/guides/model-selection-and-cost) when the
+capability is healthy but the model, repo exclusion, route volume, or cost
+policy needs a clearer operating rule.
+
+## Deep dives
+
+<Cards>
+  <Card title="Triggers" href="/web/triggers" />
+  <Card title="Assignments" href="/web/assignments" />
+  <Card title="Automations" href="/web/automations" />
+  <Card title="Observability Reference" href="/web/observability" />
+</Cards>
diff --git a/content/docs/capabilities/meta.json b/content/docs/capabilities/meta.json
@@ -0,0 +1,16 @@
+{
+  "title": "Capabilities",
+  "pages": [
+    "index",
+    "agents",
+    "routing",
+    "review-and-triage",
+    "observability",
+    "---Deep Dives---",
+    "[Agents Reference](/web/agents)",
+    "[Automations](/web/automations)",
+    "[Triggers](/web/triggers)",
+    "[Assignments](/web/assignments)",
+    "[Skills, Rules, and Context](/web/agents/skills-rules-context)"
+  ]
+}
diff --git a/content/docs/capabilities/observability.mdx b/content/docs/capabilities/observability.mdx
@@ -0,0 +1,97 @@
+---
+title: Observability
+description: Inspect Mogplex run health, pressure, model calls, tool calls, tokens, cost, sandbox linkage, and runtime errors.
+---
+
+Observability is how you understand work after it starts.
+
+Use it for runtime questions, not setup questions.
+
+## What it answers
+
+- did the work run?
+- is work pending, deferred, suppressed, running, failed, repaired, or
+  complete?
+- which surface started it: CLI, cloud, automation, or live activity?
+- which model calls happened?
+- what tools were called?
+- how many tokens were used?
+- what was the estimated cost?
+- did the run touch a sandbox?
+- what error was captured?
+
+## Read summary before detail
+
+Start with the summary cards to understand the shape of the problem:
+
+- run counts and success rate
+- stale pending work
+- suppressed and deferred starts
+- start failures
+- token usage
+- estimated cost
+- sandbox time
+
+Then open Activity rows for the event timeline, tool calls, raw metadata,
+sandbox linkage, GitHub links, and error strings.
+
+## Surface badges
+
+| Badge | Meaning |
+| --- | --- |
+| Live | The call is still pending or streaming |
+| CLI | The call came from the local CLI runtime path |
+| Cloud | The call ran outside a job-backed automation |
+| Automation | The call is attached to an automation or job run |
+
+This is the fastest way to tell whether a failure or spend spike came from
+local work, hosted work, or automation.
+
+## When not to start here
+
+Do not start in Observability when no work has actually queued or started.
+
+If a route did not fire, check the source:
+
+- [Settings](/web/settings)
+- [Installations](/web/installations)
+- [Projects](/web/spaces)
+- [Triggers](/web/triggers)
+- [Assignments](/web/assignments)
+- [Automations](/web/automations)
+- [CLI](/platform/cli)
+
+Observability can explain runtime behavior. It cannot prove why a route that
+never emitted a run did not route.
+
+## Common workflows
+
+### A run failed
+
+1. Filter Activity by failed status.
+2. Open the row for the failing call.
+3. Read the captured error and event timeline.
+4. Inspect tool calls before changing routing or agent prompts.
+
+### Spend jumped
+
+1. Read token and cost summary cards.
+2. Filter by surface.
+3. Open high-token or high-cost calls.
+4. Compare model, task, tool usage, and sandbox linkage.
+
+### A sandbox preview is unhealthy
+
+1. Start from [Sandboxes](/web/sandboxes) if you know the runtime.
+2. Jump into Observability with the sandbox context selected.
+3. Open the linked call or job row and inspect metadata.
+
+## Read next
+
+<Cards>
+  <Card title="Observability Page" href="/web/observability" />
+  <Card title="Observability Runbook" href="/guides/observability-runbook" />
+  <Card title="Projects and Sandboxes" href="/platform/projects-and-sandboxes" />
+  <Card title="Support" href="/support" />
+  <Card title="API Observability Routes" href="/web/api/route-families" />
+</Cards>
diff --git a/content/docs/capabilities/review-and-triage.mdx b/content/docs/capabilities/review-and-triage.mdx
@@ -0,0 +1,93 @@
+---
+title: Review and Triage
+description: Configure Mogplex for pull request review, issue triage, CI failure investigation, GitHub mentions, and follow-up edits.
+---
+
+Review and triage are the most common hosted Mogplex workflows.
+
+They share setup, but they should not use the same agent role by default.
+
+## Pick the right job shape
+
+| Job | Best starting surface |
+| --- | --- |
+| Every PR in one repo should be reviewed | [Assignments](/web/assignments) |
+| Every PR event in one installation should wake a reviewer | [Triggers](/web/triggers) |
+| Review should branch into an edit step only when findings are real | [Automations](/web/automations) |
+| New issues need labeling, reproduction guidance, or routing | [Assignments](/web/assignments) or [Triggers](/web/triggers) |
+| A human wants to ask from a PR or issue thread | [GitHub mention routing](/web/guides/github-mention-routing) |
+| CI failure should be investigated and optionally fixed | [Assignments](/web/assignments), [Triggers](/web/triggers), or [Automations](/web/automations) |
+
+## Agent roles
+
+Use `review` when the agent should inspect code changes and produce findings.
+
+Use `triage` when the agent should understand a thread or event, classify it,
+respond, label, or decide the next step.
+
+Use `edit` when the graph has already decided code should be changed.
+
+That split keeps mutation explicit. A reviewer can report findings, while a
+follow-up edit node can apply changes only after the workflow decides it should.
+
+## Common patterns
+
+### Standing PR review
+
+Use an [Assignment](/web/assignments) when one repo should always use the same
+review behavior. This keeps the repo as the durable unit of responsibility.
+
+### Lightweight event review
+
+Use a [Trigger](/web/triggers) when a GitHub event should wake one review agent
+without a workflow graph.
+
+### Review then fix
+
+Use an [Automation](/web/automations) when the route should:
+
+- review first
+- branch on whether findings are real
+- edit only on the fix branch
+- keep draft changes separate until the workflow is published
+
+### Issue triage
+
+Use a `triage` agent for new issues and issue comments. The agent should
+classify, summarize, request missing information, route, or answer. It should
+not be forced into code-review behavior unless the issue explicitly carries a
+diff or reproduction branch.
+
+### GitHub mentions
+
+Use exact mention syntax:
+
+```text
+@mogplex summarize the failing check
+@mogplex/triage label this and suggest next steps
+@mogplex/reviewer review this diff with extra attention to auth
+```
+
+For targeted mentions, the part after `/` must match an agent slug.
+
+## After work starts
+
+Use [Observability](/web/observability) to answer:
+
+- did the job run?
+- did it fail, defer, suppress, or queue?
+- what model and tools were used?
+- what did it cost?
+- which sandbox or GitHub object was involved?
+
+If no run exists, go back to [Routing](/capabilities/routing) and check setup
+before inspecting runtime detail.
+
+## Read next
+
+<Cards>
+  <Card title="Automation Agent Roles" href="/web/automations/agent-roles" />
+  <Card title="Common Use Cases" href="/guides/common-use-cases" />
+  <Card title="Routing" href="/capabilities/routing" />
+  <Card title="Observability" href="/capabilities/observability" />
+</Cards>