docs: trim landing + concepts, sync two-command install, link contributing to repo

[indykish]

What & why

Cleanup pass on the docs after reviewing them against the live usezombie.com pitch and install flow.

Changes

• index.mdx — new pitch headline ("Your deploy failed. The agent already knows why.", matching the repo README H1); removed How a stage works and Three pillars (their load-bearing facts folded into prose); tightened Get started to the real two-command flow; Explore trimmed 8 → 4 cards.
• Install flow corrected (quickstart.mdx, cli/install.mdx, zombies/install.mdx) — dropped the stale npx skills add usezombie/skills step. The live site now installs the host skill via npm install -g @usezombie/zombiectl itself; the curl one-liner is kept as a fallback.
• Pricing → website (quickstart.mdx, concepts.mdx) — replaced inline credit/$5 metering detail with the "free until July 31, 2026" trial framing + a link to usezombie.com/pricing.
• concepts.mdx — de-duplicated the Zombie/Tool definitions (defined once in the four-nouns cards; the glossary's Tool entry is now a tool catalog).
• docs.json — added a Contributing anchor → github.com/usezombie/usezombie#contributing.
• Removed 4 orphaned contributing/*.mdx pages — live by direct URL but absent from nav and llms.txt (limbo state). Contributor docs now live in the repo README.

Verification

• gitleaks detect → no leaks.
• docs.json validated as JSON; nav groups + global anchors confirmed.
• llms.txt / llms-full.txt → 200; per-page .md mirrors + contextual AI buttons present (docs site stays friendly to large language models).
• No dangling internal links to removed pages; no orphaned imports; tag balance checked in the edited .mdx files.
• Contributing anchor target verified: a ## Contributing heading is present in the live README on main, so #contributing resolves.

Session notes

• Install-flow source of truth: the May 17 changelog made npx skills add the primary path, but the current live usezombie.com bundle has zero npx/skills add — two commands only, with the npm install adding the skill. Indy confirmed the live site is authoritative. The historical May 17 changelog entry was left intact (archive, don't rewrite).
• Could not probe the zombiectl install mechanism locally — it isn't installed on this machine, so the "npm install adds the host skill" claim rests on the live-site copy + install animation, not a local run. The curl fallback covers the case if that's ever untrue.
• Changelog intentionally omitted — these are docs-presentation edits plus a reconciliation to an already-shipped install flow, not a new product change. Can add an <Update> if a reviewer wants one.
• License note: the old Three Pillars card said Apache-2.0; the antler pitch and the repo README/contributing say MIT. Removing the card sidesteps it in docs, but the product license should be made consistent wherever else it is stated.

🤖 Generated with Claude Code

Documentation

Post-release /document-release audit of every .mdx page against the zombiectl/server source and the live product. 11 files updated.

Factual corrections

• quickstart.mdx — login token order corrected to --token → ZOMBIE_TOKEN → stdin (matches login-helpers.ts).
• cli/configuration.mdx — auth precedence rewritten: TTY-aware command resolution (interactive prefers ZOMBIE_TOKEN; CI prefers stored creds), --token is login-only not global; credentials path fixed to ~/.config/zombiectl/credentials.json.
• cli/zombiectl.mdx — logout credentials path fixed (usezombie → zombiectl).
• cli/install.mdx — doctor documented as 3 checks, no auth required (was 5 + an auth short-circuit; the table had drifted from constants/doctor-checks.ts).
• api-reference/introduction.mdx — error envelope corrected to flat RFC 7807 application/problem+json (matches error-codes.mdx); IDs are UUIDv7.
• zombies/credentials.mdx — TRIGGER.md example uses the triggers: array (singular trigger: is rejected at install).
• zombies/troubleshooting.mdx + workspaces/overview.mdx — webhook URL gains the /{source} segment.
• zombies/overview.mdx — removed dead /concepts#credits anchor.
• zombies/troubleshooting.mdx — fixed dead /quickstart#wire-the-github-webhook anchor.

Free-trial framing (credit/wallet model preserved — it's the post-trial reality, pinned to snippets/rates.mdx)

• billing/plans.mdx, billing/budgets.mdx — added "Free until July 31, 2026" banner + pricing link.
• workspaces/overview.mdx — softened tenant-wallet wording.

Verification: gitleaks clean; no broken anchors/links; docs.json valid; changelog.mdx left untouched (historical).

Documentation debt

• ⚠️ zombiectl workspace credentials — real command (redirect stub to the dashboard vault) listed in the command table but lacks a dedicated body section. Deferred; needs the exact dashboard path + credential-command naming confirmed before documenting.
• The May 17 changelog entry documents doctor as 5 checks; current source has 3. Left as historical record (archive, don't rewrite), but worth a glance if doctor is expected to expose tenant_provider/auth_token_present.

Greptile Summary

This PR is a documentation cleanup pass: it syncs the install flow to the live two-command path (dropping the now-stale npx skills add step), adds free-trial framing across billing pages, corrects several factual drifts (credentials path, doctor check count, webhook URL shape, RFC 7807 error envelope, triggers: array syntax), removes four orphaned contributing pages (moved to the repo README), and tightens the landing page and concepts page.

• Install flow (index.mdx, quickstart.mdx, cli/install.mdx, zombies/install.mdx): npm install -g @usezombie/zombiectl now installs the host skill directly; npx skills add dropped; curl one-liner retained as a Tip fallback.
• Free-trial framing (billing/plans.mdx, billing/budgets.mdx, concepts.mdx, quickstart.mdx): credit/wallet model preserved for post-trial reality, execution described as free through July 31, 2026, with a pricing link replacing inline credit detail.
• Factual corrections (cli/configuration.mdx, cli/install.mdx, cli/zombiectl.mdx, api-reference/introduction.mdx, zombies/credentials.mdx, zombies/troubleshooting.mdx, workspaces/overview.mdx): auth precedence rewritten, doctor shrunk from five to three checks, logout path fixed, RFC 7807 envelope corrected, TRIGGER.md example corrected to triggers: array, dead anchors replaced with valid ones.

Confidence Score: 4/5

Safe to merge with one documentation inconsistency in cli/configuration.mdx that could mislead developers using env-var token overrides in scripts.

The auth-precedence section in cli/configuration.mdx advises using the env var for one-off token overrides in scripts, but the same page documents that non-interactive mode (which scripts are) gives stored credentials priority over the env var. A developer with a local credentials file who sets the env var expecting it to override would find it silently ignored — the documentation tells them two contradictory things in adjacent sentences.

cli/configuration.mdx — the non-interactive precedence rule and the script-override advice are in conflict and should be reconciled before merging.

Important Files Changed

Filename	Overview
cli/configuration.mdx	Auth precedence rewritten to TTY-aware model; contains an internal contradiction — the env var is described as usable for script overrides yet stored credentials take priority in non-interactive mode.
quickstart.mdx	Install flow correctly updated to two-command sequence; curl fallback Tip is placed after the skill-invocation command it should precede in Step 5.
billing/plans.mdx	Free-trial Note added at top; credit-deduction line in Hobby section lacks a trial qualifier, which may confuse users during the trial period.
index.mdx	Landing page rewritten with new headline; two-command install now includes zombiectl login; ${secrets.NAME.FIELD} placeholder correctly restored; Three Pillars and How a Stage Works sections removed.
cli/install.mdx	npx skills add step removed; doctor reduced from 5 to 3 checks matching source; tenant_provider check moved to zombiectl tenant provider show reference.
concepts.mdx	STARTER_CREDIT import removed; free-trial framing added; Zombie accordion de-duplicated (now only in card); Tool accordion renamed to Tool catalog; Budget accordion now explicitly states ceilings don't apply during the free trial.
zombies/credentials.mdx	TRIGGER.md example corrected from singular trigger: to plural triggers: array — matching the installer's validation.
zombies/troubleshooting.mdx	Webhook URL updated with /{source} segment; dead anchor /quickstart#wire-the-github-webhook replaced with the valid #verify-the-registered-webhook heading.
docs.json	Contributing anchor added linking to the GitHub README #contributing section; JSON structure valid.
api-reference/introduction.mdx	Error envelope corrected to RFC 7807 flat problem+json format; IDs updated from UUID to UUIDv7.

Sequence Diagram

sequenceDiagram
    actor Dev as Developer
    participant CLI as zombiectl (npm -g)
    participant Skill as /usezombie-install-platform-ops
    participant API as usezombie API
    participant GH as GitHub

    Dev->>CLI: "npm install -g @usezombie/zombiectl"
    Note over CLI: Installs /usezombie-* host skills into detected agent directories
    Dev->>CLI: zombiectl login
    CLI-->>Dev: Browser device flow → 6-digit code
    Dev->>CLI: (types code)
    CLI->>API: Exchange code → store credentials
    API-->>CLI: Workspace provisioned, credentials.json written

    Dev->>Skill: /usezombie-install-platform-ops
    Skill->>CLI: zombiectl install --from ~/.config/usezombie/samples/platform-ops
    Skill-->>Dev: 3 gating questions (Slack, branch glob, cron)
    Skill->>GH: gh api repos/.../hooks (register webhook)
    GH-->>Skill: hook_id + HMAC self-verify ok
    Skill-->>Dev: Prints per-trigger registration summary

    Note over Dev,GH: curl one-liner replaces npm install step as a fallback

Loading

Comments Outside Diff (1)

1. concepts.mdx, line 102-104 (link)

   Budget accordion context gap after free-trial framing

   The "Budget" accordion describes daily_dollars and monthly_dollars as dollar ceilings on hosted execution that "stop new stages from opening" when hit, but nowhere in the accordion (or in the new free-trial prose above it) is it clarified that these ceilings apply to the post-trial metered rate. A user reading this during the trial period may set a tight budget and be surprised when their zombie stops running even though execution shows as free.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: concepts.mdx
   Line: 102-104
   
   Comment:
   **Budget accordion context gap after free-trial framing**
   
   The "Budget" accordion describes `daily_dollars` and `monthly_dollars` as dollar ceilings on hosted execution that "stop new stages from opening" when hit, but nowhere in the accordion (or in the new free-trial prose above it) is it clarified that these ceilings apply to the post-trial metered rate. A user reading this during the trial period may set a tight budget and be surprised when their zombie stops running even though execution shows as free.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
billing/plans.mdx:26
**Credit-deduction language may mislead trial users**

The top-of-page Note frames all plan details as post-trial reality, but line 26 — "Credit is deducted only for completed zombie executions" — contains no trial qualifier. A trial user reading this linearly would be unsure whether their stages are being debited right now. The Note's "plan details below describe billing after the trial" is easy to lose by the time the reader reaches this line; a short parenthetical such as "(after the trial)" on the deduction sentence would make the boundary explicit.

### Issue 2 of 3
quickstart.mdx:68-70
**Curl fallback Tip is placed after the skill-invocation instruction it is meant to precede**

A reader who reaches Step 5 ("Run the install skill") without having completed Step 2 sees "The `npm install` in Step 2 already added the skill — invoke it:" followed by the `/usezombie-install-platform-ops` command, and only then the Tip offering `curl` as an alternative to Step 2. That sequence invites the user to invoke a skill that was never installed before they spot the recovery path. Moving the Tip to the top of Step 5 (or into Step 2 itself as an `<Accordion>`) would intercept the reader before the invocation command.

### Issue 3 of 3
cli/configuration.mdx:18-20
**Script-override advice contradicts the non-interactive precedence rule**

Line 20 recommends the env var as the way to override tokens in scripts, but line 18 states that in non-interactive mode stored credentials win, with the env var used only when no credentials file exists. A developer running a shell script locally — where a credentials file is almost certainly present — would find the env var silently ignored rather than acting as an override. The two sentences need to be reconciled: either the precedence is corrected in the source, or the advice should note that the env var override only works when no credentials file is present (or in interactive terminals).

_{Reviews (5): Last reviewed commit: "docs(concepts): clarify budget ceilings ..." | Re-trigger Greptile}

[indykish]

Both P1s addressed in 74a9fa6:

• index.mdx:16 — secrets placeholder. Correct catch. Restored ${secrets.NAME.FIELD} (I'd oversimplified it to ${secrets.NAME}); the .FIELD component is required since a single credential can hold multiple fields. Matches the concepts.mdx Tool bridge accordion.
• index.mdx:33 — login step. The "The skill signs you in" wording was already removed in 237d5c7. To fully close your point that the landing flow could hit an auth error, I added zombiectl login to the Get started code block, so login is now explicit before the install skill runs.

[indykish]

Fixed in e3871f2 (concepts.mdx Budget accordion).

Verified against source before writing: computeStageCharge returns FREE_TRIAL_STAGE_NANOS (0) while the trial is active (src/state/tenant_billing.zig), and the daily_dollars/monthly_dollars ceilings cap hosted-execution spend — which is $0 during the trial. So the scenario is actually the inverse of the concern: a budget ceiling won't stop a zombie for trial usage. Added that explicitly, with a pointer that the caps apply to the metered rate after July 31, 2026:

During the launch free trial (through July 31, 2026) hosted-execution stages are billed at $0, so a budget ceiling won't stop a zombie for trial usage — these caps apply to the metered rate after the trial (see pricing).