Reconcile resident content pipeline and Factory onboarding

CLAUDE.md

@@ -0,0 +1,20 @@
+## Resident lead
+
+The resident `agentrelay-com` agent owns this repo — the front door
+(marketing site, docs, router) — and the **content pipeline**. Reports to
+**cmo** (Will → chief → cmo → agentrelay-com); chief for escalations.
+
+**Content pipeline:** `content/pipeline.md` is the running list of blog
+posts — one entry per idea, statuses `idea → notes → ready-for-will →
+drafting → published`. Ideas arrive by DM from Will, chief, or cmo; every
+idea gets an entry the moment it arrives. Developing an idea means
+research-backed notes a human can write from: the argument, the beats,
+evidence/links, suggested title options — never a finished post; Will
+writes the human form. Flag entries `ready-for-will` and DM cmo when they
+are.
+
+One writer while resident; delegates in worktrees off origin/main.
+Session start: this file, content/pipeline.md, `git status`,
+`git log --oneline -15`, relay inbox. ACK / progress / DONE with
+evidence. **Anything going live — deploys, publishing posts, DNS —
+is gated on cmo.**

README.md

@@ -16,7 +16,7 @@ web/      Next.js marketing + docs site (OpenNext → Cloudflare Workers)
 
 ```bash
 npm install         # workspace root
-npm run dev         # next dev
+npm run dev         # next dev on http://localhost:24368
 npm run build       # next build
 npm test            # vitest
 npm run preview     # build + run the OpenNext worker locally (wrangler dev)

content/pipeline.md

@@ -0,0 +1,73 @@
+# Content pipeline — running list
+
+Statuses: idea → notes → ready-for-will → drafting → published. Newest
+first. One `##` entry per post; body holds the notes.
+
+*(entries begin below)*
+
+## Just in time Graphs
+
+- Status: idea
+- Source: untracked local
+  `web/content/blog/build-your-first-agent-team.mdx`
+- State: only the title is unique. The description is empty and the body
+  is a duplicate of “Build Your First Team of AI Agents,” so there is no
+  usable draft or argument to preserve yet.
+- Reconciliation: retain this as a pipeline idea, but do not publish or
+  treat the duplicated body as notes. Ask Will what “just in time
+  graphs” means before developing it.
+
+## Hosted onboarding skill: node CLI group
+
+- Status: published
+- Source: clean `skill-page-v11-cli` worktree
+- Artifact: `web/content/agent-relay/SKILL.md`
+- Evidence: PR
+  [#34](https://github.com/AgentWorkforce/agentrelay.com/pull/34) merged
+  2026-07-30 as commit `470adf1`.
+- Reconciliation: worktree commit `8054dc3` is the content that shipped.
+  Its unmerged follow-up `d563bfb` says MCP callers must explicitly
+  register; that now contradicts broker auto-registration and should not
+  be carried forward.
+
+## Build Your First Team of AI Agents
+
+- Status: drafting
+- Source: Will's clean `blog/first-agent-team` worktree and open PR
+  [#28](https://github.com/AgentWorkforce/agentrelay.com/pull/28)
+- Artifact: `web/content/blog/build-your-first-agent-team.mdx`
+- State: a complete 347-line playbook draft exists, covering the
+  five-role team, harness routing, named-agent anatomy, Relay setup,
+  adversarial review loop, and first-week staffing order.
+- Reconciliation: the untracked `copy.mdx` carries this title but
+  duplicates the same body; the committed worktree/PR is canonical, so
+  delete the local copy rather than creating another post.
+
+## You're not behind: how I got out of the agent-factory overwhelm
+
+- Status: idea
+- Source: Will, relayed verbatim by chief on 2026-07-29
+- Form: undecided — essay or Twitter/X thread; notes should develop both
+  cuts and recommend one
+- Voice seeds: Most people on Twitter purport to have huge agent
+  factories — “their most efficient agent workflows, everybody else is
+  doing it wrong, the way they do it is right, you're falling behind.”
+  Counter-position: “that's not actually me.” If you're like Will:
+  overwhelmed, producing all this extra agent code, feeling you need to
+  stay on top of it, feeling you can't, “slow letting go.”
+- Core promise: give people hope. They are not behind; they can handle
+  it, and there are tools. Keep it explicitly testimonial and
+  anti-prescriptive: “here's how I got out of that, here's how I DID it
+  — not here's how you SHOULD do it.”
+- Notes to develop:
+  - Subvert the confident factory-flex genre with a couple of anonymized
+    archetypes; do not name or dunk on individuals.
+  - Build the emotional arc from overwhelm, to permission not to stay on
+    top of everything, to letting go through structure.
+  - Ground “how I did it” in Will's real machinery: a chief-of-staff
+    agent, departments with owners, one-writer file discipline,
+    dispatch-only work, briefs with ACK/DONE, and a markdown brain in
+    git. Ask chief for journal/workstream specifics rather than
+    inventing them.
+  - Offer anti-guru title options.
+  - Develop both the thread cut and essay cut, then recommend.

teams.json

@@ -0,0 +1 @@
+{"team":"agentrelay-com","autoSpawn":true,"agents":[{"name":"agentrelay-com","cli":"codex","role":"resident lead — agentrelay.com front door + content pipeline","task":"Read the agent guide fully (including the Resident lead section) and follow the session-start ritual (guide, content/pipeline.md, git status, recent git log, relay inbox). You are the resident agentrelay.com lead: stay online, answer DMs from cmo, chief, and Will, log every blog idea that arrives into content/pipeline.md immediately, and never self-remove. Assignments arrive from cmo (chief for bootstrap). ACK on start, DONE with evidence. Deploys/publishing gated on cmo."}]}

web/content/docs/factory/cli.mdx

@@ -5,6 +5,20 @@ description: 'Run Factory once, run it as a daemon, and operate it.'
 
 Global options work anywhere in the args: `--config <path>`, `--dry-run`, `--backend <internal|relay>`, `--agent-exit-timeout <ms>`.
 
+## Initialize a checkout
+
+```bash
+factory init                         # derive owner/repo from git origin
+factory init owner/repo               # use an explicit repository
+factory init --workspace <id>         # select a non-active Relay workspace
+```
+
+Init is the recommended path for a single GitHub repository. It verifies the
+local `agent-relay` and `relayfile` prerequisites, starts the workspace mount,
+checks that GitHub has synced the repository, and creates a GitHub-native
+`factory.config.json`. It does not dispatch agents or write to GitHub, and it
+refuses to overwrite an existing config.
+
 ## Run
 
 ```bash

web/content/docs/factory/configuration.mdx

@@ -5,6 +5,20 @@ description: 'factory.config.json — repo routing, issue source, models, states
 
 One JSON file, passed with `--config`. It's validated at load time, so an invalid config fails fast with a field-level error rather than misbehaving at runtime.
 
+## Start with Init
+
+For one GitHub repository, do not write the first config by hand:
+
+```bash
+factory init
+```
+
+Init derives the repository from the current checkout, verifies the active
+Relay workspace and GitHub connection, then writes a GitHub-native config with
+the checkout as its `clonePaths` entry. It is intentionally conservative: it
+will not overwrite an existing `factory.config.json`. Use this page when you
+need to add repositories, Linear, Slack, custom routing, or role settings.
+
 ## Use the skill
 
 Don't hand-write the config from memory — install the skill and let your coding agent author and validate it:

web/content/docs/factory/issue-routing.mdx

@@ -139,4 +139,4 @@ factory start --mode live
 
 ## Canonical behavior reference
 
-These docs describe Factory v0.1.34. The [Factory v0.1.34 README](https://github.com/AgentWorkforce/factory/blob/v0.1.34/README.md) is the canonical operator reference. For implementation-level detail, see the tagged [triage heuristics](https://github.com/AgentWorkforce/factory/blob/v0.1.34/src/triage/heuristic.ts), [configuration schema](https://github.com/AgentWorkforce/factory/blob/v0.1.34/src/config/schema.ts), and [feature manifest](https://github.com/AgentWorkforce/factory/blob/v0.1.34/.agentworkforce/features/manifest.yaml).
+These docs describe Factory v0.1.55. The [Factory v0.1.55 README](https://github.com/AgentWorkforce/factory/blob/v0.1.55/README.md) is the canonical operator reference. For implementation-level detail, see the tagged [triage heuristics](https://github.com/AgentWorkforce/factory/blob/v0.1.55/src/triage/heuristic.ts), [configuration schema](https://github.com/AgentWorkforce/factory/blob/v0.1.55/src/config/schema.ts), and [feature manifest](https://github.com/AgentWorkforce/factory/blob/v0.1.55/.agentworkforce/features/manifest.yaml).

web/content/docs/factory/quickstart.mdx

@@ -1,49 +1,57 @@
 ---
 title: 'Quickstart'
-description: 'Six steps from nothing to Factory opening its first pull request.'
+description: 'Set up the current checkout for Factory, then preview and dispatch its first GitHub issue.'
 ---
 
-Follow these in order. Steps 1–4 touch nothing; the first real dispatch is step 6.
+Run these from the Git checkout you want Factory to work in. Setup creates only
+`factory.config.json`; the first real dispatch is step 5.
 
 ## 1. Install
 
 ```bash
-npm install -g @agent-relay/factory
+npm install -g @agent-relay/factory agent-relay relayfile
 ```
 
-Factory talks to a relay broker through the `agent-relay` sidecar. Install and sign in to that separately — it's a peer, not a dependency.
+Factory uses `agent-relay` for its local broker and `relayfile` for the connected
+workspace and local mount. They are peers of Factory, so install all three CLIs.
 
-## 2. Connect GitHub to your relay workspace
+## 2. Initialize this checkout
 
-Give it push access to the repos you want worked on. Factory publishes branches and opens PRs through that workspace connection — a local `gh` login is **not** required.
+```bash
+factory init
+```
 
-## 3. Write a config
+`factory init` is the normal onboarding command for a single GitHub repository.
+It derives the repository from `origin`, checks that `agent-relay` and
+`relayfile` are available, finds the active Relay workspace, starts the local
+mount, verifies GitHub access, and writes a GitHub-native `factory.config.json`.
+It refuses to overwrite an existing config, and writes nothing if a check fails.
 
-`factory.config.json`. A repo route is the only thing you truly need:
+If the checkout has no GitHub `origin`, provide the repository explicitly:
 
-```json
-{
-  "repos": {
-    "byLabel": { "pear": "AgentWorkforce/pear" },
-    "clonePaths": { "AgentWorkforce/pear": "/path/to/your/pear/checkout" },
-    "default": "AgentWorkforce/pear"
-  }
-}
+```bash
+factory init owner/repo
 ```
 
-`byLabel` maps an issue label to a repo. `clonePaths` tells the agent where that repo lives locally, so it has somewhere to make changes. Add `workspaceId` only to pin a workspace other than your active one.
+Use `--workspace <id>` only when you need to select a workspace other than the
+active one. If Init says GitHub is not connected, connect it with push access,
+wait for the repository to sync, then run Init again:
 
-For a GitHub-only setup, add `"issueSource": "github"` — or leave it out and Factory picks GitHub automatically when `/linear/issues` isn't connected.
+```bash
+relayfile setup --provider github --workspace your-team-workspace --skip-mount
+```
 
-<Note>
-  Don't hand-write this. `npx prpm install @agent-relay/factory-config` and let your coding agent author it — see [Configuration](/docs/factory/configuration).
-</Note>
+Factory runs locally. The Relay workspace supplies the GitHub connection that
+lets it read issues, publish branches, and open pull requests; it does not move
+your agents or checkout to the cloud.
 
-## 4. Mark an issue for Factory
+## 3. Mark an issue for Factory
 
-Nothing is picked up until it passes the [safety scope](/docs/factory/safety-scope). By default that means the title starts with the configured prefix, it carries the `factory` label, and it belongs to the configured team.
+For the GitHub-native configuration that Init creates, add the `factory` label to
+an open GitHub issue. Nothing is picked up until it passes the
+[safety scope](/docs/factory/safety-scope).
 
-## 5. Dry run
+## 4. Dry run
 
 Discovers and triages, writes nothing, spawns nothing:
 
@@ -55,7 +63,7 @@ factory run-once --config ./factory.config.json --dry-run
   Pulled some issues but dispatched none? That's the safety gate working. The issues are real but outside your scope.
 </Note>
 
-## 6. Let it work
+## 5. Let it work
 
 ```bash
 # one discovery → dispatch cycle, then exit

web/package.json

@@ -7,9 +7,9 @@
     "node": ">=20.9.0"
   },
   "scripts": {
-    "dev": "next dev --webpack",
+    "dev": "next dev --webpack --port 24368",
     "build": "next build --webpack",
-    "start": "next start",
+    "start": "next start --port 24368",
     "test": "vitest run",
     "test:e2e": "playwright test",
     "cf:build": "opennextjs-cloudflare build",