docs: add software factory concept page and 5 guides

.agents/skills/draft_guide/SKILL.md

@@ -49,6 +49,29 @@ When drafting a guide, check for relevant SEO and AEO data:
 4. **Frame the title for non-branded search.** The page should answer the user's actual question, with Warp features as the natural solution in the guide body.
 5. **Avoid keyword stuffing.** Preserve high-intent query terms only where they make the guide clearer or more discoverable. Rewrite awkward source-data phrasing into natural developer language.
 
+## Oz CLI and GitHub Actions accuracy
+
+When a guide includes Oz CLI commands or GitHub Actions workflows using `warpdotdev/oz-agent-action`:
+
+- **Verify Oz CLI commands against `/reference/cli/`.** Do not infer flag names or argument formats. Use only flags documented in the CLI reference. When in doubt, link to the reference page instead of showing a command.
+- **`oz-agent-action` input format**: `warp_api_key` is a `with:` input to the action, not an `env:` variable. `GITHUB_TOKEN` goes in `env:`. The correct pattern is:
+  ```yaml
+  - uses: warpdotdev/oz-agent-action@v1
+    with:
+      skill: SKILL_NAME
+      environment: YOUR_OZ_ENVIRONMENT_SLUG
+      warp_api_key: ${{ secrets.WARP_API_KEY }}
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  ```
+- **Every GitHub Actions workflow example that performs write operations must include a `permissions:` block** at the workflow level, before `jobs:`. Use the minimum permissions for the task:
+  - Triage (label/comment on issues): `issues: write`
+  - Spec/implementation (push branches, open PRs): `contents: write`, `pull-requests: write`
+  - Review (post PR comments): `pull-requests: write`
+  Without an explicit `permissions:` block, workflows fail in repositories with restricted default permissions.
+- **`oz secret create` must not include `--value` on the command line.** The `--value` flag exposes secrets in shell history and process arguments. Show `oz secret create --name SECRET_NAME` and note that the CLI prompts for the value interactively.
+- **Slash commands** (`/command-name`) in standalone code fences should use `bash` as the language identifier, consistent with the docs style guide for terminal input.
+
 ## Third-party tool accuracy
 
 When a guide documents a third-party tool (Claude Code, Codex, OpenCode, etc.):

.agents/templates/conceptual.md

@@ -1,11 +1,10 @@
 ---
+title: [Feature or concept name — sentence case. Title convention: noun or "About [subject]". The title field renders as the page H1; do not add a separate H1 in the body.]
 description: >-
   [1-2 sentences: what the concept/feature is + why it matters.
   Write as a standalone summary for search results. Lead with user benefit.]
 ---
 
-# [Feature or concept name — sentence case. Title convention: noun or "About [subject]"]
-
 [Opening paragraph: What this feature/concept is and its primary benefit.
 1-3 sentences. Lead with what the user gains from understanding this.]
 

.agents/templates/guide-page.md

@@ -1,13 +1,10 @@
 ---
+title: [Task-oriented title in sentence case — reads like a search query. Capture the non-branded query a developer would actually search for, not "How to do X in Warp." The title field renders as the page H1; do not add a separate H1 in the body.]
 description: >-
   [1-2 sentence summary of what this guide covers and what the reader will
   achieve. Keep under 160 characters for SEO.]
 ---
 
-# [Task-oriented title in sentence case — reads like a search query]
-
-[TITLE GUIDANCE: Title should describe what the reader will DO, not what the feature IS. For SEO, capture the non-branded query — write the title a developer would actually search for, not "How to do X in Warp." Good: "How to set up Claude Code". Bad: "How to set up Claude Code in Warp".]
-
 [One sentence: what you'll accomplish by following this guide. Mention Warp by name. Include a time estimate if possible (e.g., "takes about 10 minutes").]
 
 [AEO GUIDANCE: If this guide is based on Peec, answer-engine prompts, search-query data, or AEO goals, create an AEO brief first using `.agents/skills/aeo_brief/SKILL.md`. Use the brief to preserve high-intent vocabulary naturally, translate awkward source-data phrasing into developer-friendly docs language, and decide whether this should be a new guide or an update to an existing page.]

src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx

@@ -0,0 +1,126 @@
+---
+title: Build a self-improving agent
+description: >-
+  Build an outer improvement loop where a scheduled agent reviews past runs, learns from team corrections, and proposes skill file updates — so your factory gets better over time.
+sidebar:
+  label: "Build a self-improving agent"
+tags:
+  - "agents"
+  - "software-factory"
+  - "cloud-agents"
+  - "schedules"
+---
+
+A self-improving agent is the outer loop of the [software factory](/guides/agent-workflows/set-up-a-software-factory) you've built in the previous guides. It watches how maintainers correct the inner-loop agents — relabeled issues, edited comments, changed code — and opens a pull request to improve the skill files that drive those agents. Every correction from a teammate becomes a proposed improvement to the factory.
+
+This guide shows how to build the outer loop for a triage agent. The same pattern applies to any agent role.
+
+:::note
+The outer loop proposes improvements; it doesn't apply them silently. Every change to a skill file goes through a normal pull request review before merging. The team decides what improves; the agent proposes it.
+:::
+
+## Prerequisites
+
+* A working inner loop with at least one agent running ([set up your software factory](/guides/agent-workflows/set-up-a-software-factory))
+* A Warp account ([sign up at warp.dev](https://www.warp.dev))
+* An Oz cloud environment with access to your repository ([create one](/platform/environments))
+
+## Why principles beat rules
+
+Most agent skills start as a list of rules, but rules overfit. They break when a situation arrives that the rules didn't anticipate, and a longer rule list makes the skill harder to maintain.
+
+Effective skill files describe **principles**: durable ideas about how to approach a class of situation. A principle, e.g., "confirm that a bug report includes enough context for a fresh contributor to reproduce the issue", transfers to situations the original rules didn't cover. 
+
+When the outer loop proposes a skill update, it should always aim for a principle that generalizes, not a new rule that handles one more edge case.
+
+## 1. Collect correction signals
+
+The outer loop needs signals that the inner loop got something wrong. For a triage agent, the most useful signals are:
+
+* **Maintainer relabels** — A maintainer changes a label the triage agent applied (for example, `needs-info` → `ready-to-implement`).
+* **Maintainer re-opens** — A maintainer reopens an issue the triage agent closed.
+* **Follow-up comments** — A maintainer explains in a comment why the triage agent's assessment was wrong.
+
+GitHub captures all of these in the issue timeline and audit log.
+
+The [`update-triage`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) skill in `warpdotdev/oz-for-oss` includes a Python helper script (`aggregate_triage_feedback.py`) that collects these signals for the past N days. Copy and adapt it for your repository.
+
+## 2. Create the update skill
+
+1. Create `.agents/skills/update-triage/SKILL.md` with the following content as a starting point:
+
+   ```markdown
+   ---
+   name: update-triage
+   description: Review recent maintainer corrections to the triage agent's output and propose skill file updates that generalize from those corrections.
+   ---
+
+   # Update triage skill
+
+   You are reviewing recent maintainer corrections to the triage agent's output.
+
+   ## What to look for
+
+   For each correction:
+   1. Identify what the triage agent did (the original label or comment).
+   2. Identify what the maintainer did instead (the correction).
+   3. Ask: why would the triage agent have gotten this wrong?
+   4. Ask: what principle would prevent this class of error in the future?
+
+   ## What to update
+
+   Update only the triage-issue-local companion skill for this repository.
+   Write principles, not rules. Do not update the shared triage-issue skill.
+
+   Commit changes to a branch named oz-agent/update-triage.
+   Do not push directly to main. Open a pull request for human review.
+   ```
+
+2. For the complete implementation, including the correction-collection script, write-surface restrictions, and PR-opening workflow, use the [`update-triage` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) as your reference.
+
+## 3. Schedule the outer loop
+
+Weekly is a good starting cadence: it processes the previous week's corrections and opens PRs for review at the start of the week.
+
+1. Create a scheduled cloud agent from the Oz CLI:
+
+   ```bash
+   oz schedule create \
+     --name update-triage-weekly \
+     --skill update-triage \
+     --environment YOUR_ENVIRONMENT_SLUG \
+     --cron "0 9 * * 1"
+   ```
+
+   Or, from the Oz web app: open **Agents** > **Schedules**, click **New schedule**, and set the skill, environment, and cron expression.
+
+2. Replace `YOUR_ENVIRONMENT_SLUG` with the slug of your Oz environment.
+
+See [Scheduled agents](/platform/triggers/scheduled-agents) for the full reference.
+
+## 4. Review the proposed skill changes
+
+Each time the outer loop runs, it opens a pull request with proposed changes to the `triage-issue-local` companion skill. Review that PR the same way you would review any other code change:
+
+* Does the proposed principle generalize correctly, or is it another specific rule in disguise?
+* Is the change scoped to the companion skill rather than the shared base skill?
+* Does it improve the agent's reasoning, or does it just patch one edge case?
+
+Merge the PR when the improvement is sound. Close it if the proposal is too narrow or incorrect.
+
+Over time, the companion skill accumulates a clear description of how your team thinks about issue triage — not as a list of rules, but as a set of principles that a new maintainer or a new agent can learn from.
+
+## Productivity tips
+
+* **Give feedback in the right place** — The outer loop collects signals from GitHub. If you want the triage agent to learn from a correction, add a comment to the issue explaining why the original label was wrong. That comment becomes signal for the next outer-loop run.
+* **Apply the pattern to other agent roles** — The [`update-pr-review`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-pr-review/SKILL.md) and [`update-dedupe`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-dedupe/SKILL.md) skills from `warpdotdev/oz-for-oss` apply the same outer-loop pattern to the PR reviewer and deduplication agents.
+* **Don't skip the PR review** — The value of the outer loop is compounding improvement, not speed. A bad skill change that merges silently creates more work than it saves. Every proposed change should get a review.
+
+## Next steps
+
+* [What is a software factory?](/platform/software-factory) — How the outer improvement loop fits into the full factory model.
+* [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — The inner loop the outer loop improves.
+* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to Oz for team-wide visibility.
+* [Scheduled agents](/platform/triggers/scheduled-agents) — Full reference for running cloud agents on a cadence.
+* [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation including all outer-loop skills.
+* [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz.

src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx

@@ -0,0 +1,127 @@
+---
+title: Build a triage agent for your issue backlog
+description: >-
+  Create a triage agent that reviews new GitHub issues, applies labels, and flags open questions. Your backlog stays actionable without manual effort.
+sidebar:
+  label: "Build a triage agent"
+tags:
+  - "agents"
+  - "cloud-agents"
+  - "software-factory"
+---
+
+Learn how to use Oz to build a triage agent that reviews each new GitHub issue for clarity, applies labels, and flags open questions before implementation begins. After completing the steps in this guide, you will have a working triage skill deployed as a GitHub Action. This is the first agent in your [software factory](/platform/software-factory).
+
+## Prerequisites
+
+* A Warp account ([sign up at warp.dev](https://www.warp.dev))
+* A GitHub repository with Issues enabled
+* An Oz cloud environment with access to your repository ([create one](/platform/environments#create-an-environment-with-guided-setup-recommended))
+* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys#from-the-oz-web-app-recommended))
+
+## 1. Define your triage criteria
+
+Before writing a skill, decide what your triage agent should do. A good triage agent answers three questions for every new issue:
+
+1. Is the report clear enough to act on?
+2. Is it a duplicate of an existing issue?
+3. What label should it have?
+
+Identify:
+
+* The label taxonomy for your repository (e.g., `bug`, `enhancement`, `ready-to-implement`, `needs-info`, `duplicate`).
+* Who owns each area of the codebase. This becomes your `STAKEHOLDERS` file.
+* What makes an issue "ready to implement": does it need a reproduction step, version number, or proposed approach?
+
+You will encode these decisions in a skill file in the next step.
+
+## 2. Create the triage skill
+
+A [skill](/agent-platform/capabilities/skills) is a markdown file that defines the agent's behavior. It tells the agent what to analyze, how to classify results, and what to output.
+
+1. Create a `.agents/skills/triage-issue/` directory in your repository with a `SKILL.md` file.
+2. Copy the [`triage-issue` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/triage-issue/SKILL.md) into your repository. This is the production triage skill Warp uses for its own open source repository.
+3. Adapt the skill for your repository:
+   * Replace the label taxonomy with your labels.
+   * Update the ownership section to reflect your codebase.
+   * Adjust the definition of "ready to implement" to match your team's requirements.
+4. Create `.github/issue-triage/config.json` with your label taxonomy. See the [`config.json` from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.github/issue-triage/config.json) for the format.
+
+Write the skill file in terms of principles, not rules. For example:
+* A rule says "if the reporter doesn't include a reproduction step, add `needs-info`."
+* A principle says "confirm that a bug report includes enough context for a fresh contributor to reproduce the issue."
+
+Principles transfer to situations the original rules didn't cover, while long rule lists overfit and become difficult to maintain.
+
+:::tip
+The [`bootstrap-issue-config`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/bootstrap-issue-config/SKILL.md) skill can generate initial `config.json` and `STAKEHOLDERS` files by analyzing your existing labels and `CODEOWNERS` file. Run it once when setting up a new repository.
+:::
+
+## 3. Test the triage agent locally
+
+Before deploying to GitHub Actions, test the triage agent against a real issue using the Oz CLI:
+
+```bash
+oz agent run \
+  --skill .agents/skills/triage-issue \
+  --prompt "Triage GitHub issue #ISSUE_NUMBER in OWNER/REPO" \
+  --share
+```
+
+The `--share` flag generates a session link your team can use to inspect what the agent did. Review the session output to confirm that the labels and comments are what you expect. If something is wrong, refine the skill file and run again.
+
+For the full reference of `oz agent run` flags, see the [Oz CLI reference](/reference/cli/).
+
+## 4. Deploy with GitHub Actions
+
+Once the skill output looks correct, deploy it as a GitHub Action that triggers automatically when a new issue is opened.
+
+1. In your repository, create `.github/workflows/triage-issue.yml` with the following content:
+
+```yaml
+name: Triage new issues
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: warpdotdev/oz-agent-action@v1
+        with:
+          skill: triage-issue
+          prompt: |
+            Triage GitHub issue #${{ github.event.issue.number }} in ${{ github.repository }}.
+            Issue title: ${{ github.event.issue.title }}
+            Issue body: ${{ github.event.issue.body }}
+          environment: YOUR_OZ_ENVIRONMENT_SLUG
+          warp_api_key: ${{ secrets.WARP_API_KEY }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+2. Replace `YOUR_OZ_ENVIRONMENT_SLUG` with the slug of the Oz environment you created in the prerequisites.
+
+3. Add `WARP_API_KEY` to your repository's GitHub Actions secrets under **Settings** > **Secrets and variables** > **Actions**.
+
+See [GitHub Actions integration](/platform/integrations/github-actions) for the full setup guide for `warpdotdev/oz-agent-action`.
+
+## 5. Review and improve
+
+Watch the first few runs in the [Oz web app](https://oz.warp.dev) to verify the agent is labeling and commenting correctly. When you disagree with the agent, e.g., when you relabel an issue or edit a comment, note the pattern. Patterns you see repeatedly are signals to update your skill file.
+
+Add repo-specific context without forking the core skill by creating a `triage-issue-local` companion skill. This file specializes the base skill for your repository (your label taxonomy, ownership map, and definition of readiness) while keeping the shared skill stable. See the [docs repo example](https://github.com/warpdotdev/docs/blob/main/.agents/skills/triage-issue-local/SKILL.md) for the companion skill pattern.
+
+## Next steps
+
+* [What is a software factory?](/platform/software-factory) — How the triage agent fits into the full development loop.
+* [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged.
+* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections.
+* [GitHub Actions integration](/platform/integrations/github-actions) — Full documentation for `warpdotdev/oz-agent-action`.
+* [Run agents unattended](/guides/agent-workflows/how-to-run-unattended-agents) — Broader patterns for cloud agents triggered by external events.