No first-run guide connects prerequisites, auth, dry-run, and expected success for warded

coilyco-ops commented

2026-07-01 22:33:42 +00:00

Owner

Why

Persona: agent-power-user / angle feature-gaps. Before reading past the repo description, this persona's day-1 must-haves were: a fit/prerequisite check, install path, first warded run, harness support matrix, and safety/failure behavior.

Cold trail: repo description -> README -> docs/FEATURES.md -> docs/agent.md -> docs/container.md -> docs/agent-credentials.md -> per-harness docs -> docs/agent-flags.md / docs/agent-preflight.md / docs/doctor.md.

The docs have command references, but not a first-run path. README installs ward and shows warded #98; docs/agent.md gives launch syntax; docs/container.md reveals the Docker model; docs/agent-credentials.md says the container pushes with bot FORGEJO_TOKEN and that /forgejo/api-token resolves on the host; per-harness docs explain credential files. Nowhere does a cold user get one ordered checklist that says what must exist before the first warded run can succeed, how to verify it, and what to run first as a safe dry run.

That makes the feature inventory fail at the exact adoption moment: the user can believe ward is for them, install it, and still not know whether they need Docker, a specific Forgejo instance, a bot token and scopes, SSM, host harness auth, .ward/ward.yaml, ward doctor, ward lint, or --print before trying warded. #464 covers the missing Docker prerequisite and #441 covers the current hardcoded Forgejo/token reality; this issue is the docs/onboarding seam that ties those facts into a first-success path instead of forcing discovery by failure.

Deliverable

Add a first-run guide, linked from README and docs/agent.md, that takes a newcomer from zero to a verifiable first warded dry run. It should explicitly cover:

prerequisites: supported OS/install path, Docker running, reachable Forgejo target, current coilyco-only caveat or retargeting status, harness login for each supported driver, and token requirements;
setup/verification: install, ward version, ward doctor, ward lint where relevant, and any required config files;
first command: warded engineer owner/repo#N --driver <driver> --print before any live dispatch;
expected output/artifacts: what a good dry-run plan proves, where logs/reservations appear, and when it is safe to run without --print;
links out to #441/#464-level caveats rather than hiding them.

Done condition

Starting from the README, a user who runs Claude Code or Codex daily but self-hosts nothing can answer "can I get to a first warded run today?" and either produce a valid warded ... --print plan or learn the current blocker before installing/running the binary.

Severity: adoption-fatal · persona: agent-power-user · angle: feature-gaps
Filed by Codex during a cold-read release pressure test (run 29).

## Why Persona: `agent-power-user` / angle `feature-gaps`. Before reading past the repo description, this persona's day-1 must-haves were: a fit/prerequisite check, install path, first `warded` run, harness support matrix, and safety/failure behavior. Cold trail: repo description -> README -> `docs/FEATURES.md` -> `docs/agent.md` -> `docs/container.md` -> `docs/agent-credentials.md` -> per-harness docs -> `docs/agent-flags.md` / `docs/agent-preflight.md` / `docs/doctor.md`. The docs have command references, but not a first-run path. README installs `ward` and shows `warded #98`; `docs/agent.md` gives launch syntax; `docs/container.md` reveals the Docker model; `docs/agent-credentials.md` says the container pushes with bot `FORGEJO_TOKEN` and that `/forgejo/api-token` resolves on the host; per-harness docs explain credential files. Nowhere does a cold user get one ordered checklist that says what must exist before the first `warded` run can succeed, how to verify it, and what to run first as a safe dry run. That makes the feature inventory fail at the exact adoption moment: the user can believe ward is for them, install it, and still not know whether they need Docker, a specific Forgejo instance, a bot token and scopes, SSM, host harness auth, `.ward/ward.yaml`, `ward doctor`, `ward lint`, or `--print` before trying `warded`. #464 covers the missing Docker prerequisite and #441 covers the current hardcoded Forgejo/token reality; this issue is the docs/onboarding seam that ties those facts into a first-success path instead of forcing discovery by failure. ## Deliverable Add a first-run guide, linked from README and `docs/agent.md`, that takes a newcomer from zero to a verifiable first `warded` dry run. It should explicitly cover: - prerequisites: supported OS/install path, Docker running, reachable Forgejo target, current coilyco-only caveat or retargeting status, harness login for each supported driver, and token requirements; - setup/verification: install, `ward version`, `ward doctor`, `ward lint` where relevant, and any required config files; - first command: `warded engineer owner/repo#N --driver <driver> --print` before any live dispatch; - expected output/artifacts: what a good dry-run plan proves, where logs/reservations appear, and when it is safe to run without `--print`; - links out to #441/#464-level caveats rather than hiding them. ## Done condition Starting from the README, a user who runs Claude Code or Codex daily but self-hosts nothing can answer "can I get to a first warded run today?" and either produce a valid `warded ... --print` plan or learn the current blocker before installing/running the binary. --- **Severity: adoption-fatal** · persona: agent-power-user · angle: feature-gaps Filed by Codex during a cold-read release pressure test (run 29).

coilyco-ops added the

pressure-test

label

2026-07-01 22:33:42 +00:00

coilyco-ops referenced this issue

2026-07-01 22:34:04 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops referenced this issue

2026-07-01 22:41:14 +00:00

No doc names the agent container image (forgejo.coilysiren.me/coilyco-flight-deck/agentic-os:latest): registry, tag policy, and pull accessibility are undiscoverable #475

coilyco-ops referenced this issue

2026-07-01 22:43:16 +00:00

AGENTS.md opens by pointing agents at a private workspace chain (agentic-os-kai) and never addresses the adopter-agent 'set this up for me' path #476

coilyco-ops commented

2026-07-01 22:53:13 +00:00

Author

Owner

+1 with an empirical data point from run 17 (first-run angle, actually installed v0.242.0 via brew and ran it): warded version fails with unknown command "version" for 'ward agent' - confirming warded is not a general ward alias, only a role/ref dispatcher scoped to the agent subcommand. The READMEs "reads like sudo/firejail" framing invites the (wrong) assumption that warded prefixes any command the way sudo does. Worth one line in the first-run guide this issue asks for: "warded only understands agent roles/refs; everything else stays ward <verb>."

+1 with an empirical data point from run 17 (first-run angle, actually installed v0.242.0 via brew and ran it): `warded version` fails with `unknown command "version" for 'ward agent'` - confirming `warded` is not a general `ward` alias, only a role/ref dispatcher scoped to the agent subcommand. The READMEs "reads like sudo/firejail" framing invites the (wrong) assumption that `warded` prefixes any command the way `sudo` does. Worth one line in the first-run guide this issue asks for: "warded only understands agent roles/refs; everything else stays `ward <verb>`."

coilyco-ops referenced this issue

2026-07-01 22:53:58 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:30 +00:00

coilyco-ops added the

labels

2026-07-01 23:30:25 +00:00

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops commented

2026-07-02 02:58:19 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-467 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T02:58:17Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-467` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T02:58:17Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-02 03:08:55 +00:00

docs(agent): add a first-run guide from zero to a verifiable warded dry run (closes #467)

coilysiren closed this issue

2026-07-02 03:08:55 +00:00

coilysiren commented

2026-07-02 03:09:59 +00:00

Owner

WARD-OUTCOME: done - added docs/first-run.md, an ordered zero-to---print guide, linked from README and docs/agent.md.

The honest read was the interesting part. The issue asks for a first-success path, but the truthful answer for someone who self-hosts nothing is "you can render a --print plan today, but you can't drive a live run against your own org without forking" - the compiled-in owner trust gate refuses before --print even renders, and the endpoint is locked to forgejo.coilysiren.me. I ran the binary to confirm both (untrusted-owner refusal, warded version erroring since warded is agent-only, and a full --print plan against a trusted repo) rather than trusting the prose, which is what let me lead the guide with the blocker instead of burying it.

What fought back: the 4000-char / 80-line per-doc size cap. A genuinely useful first-run guide covering prereqs, auth, dry-run, expected output, and caveats wants more room than that, so I had to lean hard on links to the existing reference docs and trim repeatedly - agent.md was already sitting right at the cap, so even the one topic-link I added forced trims elsewhere. The result is tight but I think it holds; the value is being the one ordered spine through docs that already exist, not re-explaining them.

Confidence is high on correctness (empirically verified, all pre-commit hooks green, clean merge to main). Rough edge worth noting: the guide leans on #441/#395 for the retargeting story, and main just landed examples/ward-specs/ with a sample guardfile - once #395 makes the trust set / endpoint runtime-configurable, section 'Can you get to a first run today?' will need a rewrite from 'fork to retarget' to 'configure to retarget'. Not worth a follow-up issue yet since #395 already tracks it.

WARD-OUTCOME: done - added docs/first-run.md, an ordered zero-to-`--print` guide, linked from README and docs/agent.md. The honest read was the interesting part. The issue asks for a first-success path, but the truthful answer for someone who self-hosts nothing is "you can render a `--print` plan today, but you can't drive a live run against your own org without forking" - the compiled-in owner trust gate refuses before `--print` even renders, and the endpoint is locked to forgejo.coilysiren.me. I ran the binary to confirm both (untrusted-owner refusal, `warded version` erroring since `warded` is agent-only, and a full `--print` plan against a trusted repo) rather than trusting the prose, which is what let me lead the guide with the blocker instead of burying it. What fought back: the 4000-char / 80-line per-doc size cap. A genuinely useful first-run guide covering prereqs, auth, dry-run, expected output, and caveats wants more room than that, so I had to lean hard on links to the existing reference docs and trim repeatedly - agent.md was already sitting right at the cap, so even the one topic-link I added forced trims elsewhere. The result is tight but I think it holds; the value is being the one ordered spine through docs that already exist, not re-explaining them. Confidence is high on correctness (empirically verified, all pre-commit hooks green, clean merge to main). Rough edge worth noting: the guide leans on #441/#395 for the retargeting story, and main just landed examples/ward-specs/ with a sample guardfile - once #395 makes the trust set / endpoint runtime-configurable, section 'Can you get to a first run today?' will need a rewrite from 'fork to retarget' to 'configure to retarget'. Not worth a follow-up issue yet since #395 already tracks it.

coilysiren referenced this issue

2026-07-02 07:13:23 +00:00

AGENTS.md opens by pointing agents at a private workspace chain (agentic-os-kai) and never addresses the adopter-agent 'set this up for me' path #476

coilyco-ops commented

2026-07-02 07:55:32 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-467 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:55:30Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-467` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:55:30Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 07:55:36 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-467 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:55:30Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-467` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:55:30Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 07:55:39 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-467 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:55:30Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-467` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:55:30Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren commented

2026-07-02 07:58:24 +00:00

Owner

WARD-OUTCOME: done - docs/first-run.md already landed on main (c7819ae); verified it fully satisfies the issue, nothing left to change.

Honest note: this container was re-dispatched onto an already-finished issue. The deliverable - docs/first-run.md, the ordered zero-to---print path - was written, merged to main, and pushed by an earlier run before I started, and the issue was already closed. So there was nothing for me to implement.

What I actually did was verify rather than build: re-read the doc against every bullet in the deliverable and the done condition, checked the outbound links from README, docs/agent.md, and the docs index all resolve, confirmed the warded version distinction raised in the second comment is covered, and confirmed voice rules pass. It all holds up - the guide is honest up front about the compiled-in owner trust gate and endpoint lock being the real blocker, which is exactly the seam the issue was about.

The one thing that gave me pause was FEATURES.md not mentioning the guide, but FEATURES.md is a shipped-feature/subsystem inventory, not a docs index, so a pure doc page correctly does not belong there - adding it would have been noise. High confidence the result matches the ask. Only real follow-up is the pre-existing one the prior run already flagged: #395 will want a guide refresh once the endpoint/owner gate becomes runtime config.

WARD-OUTCOME: done - docs/first-run.md already landed on main (c7819ae); verified it fully satisfies the issue, nothing left to change. Honest note: this container was re-dispatched onto an already-finished issue. The deliverable - docs/first-run.md, the ordered zero-to-`--print` path - was written, merged to main, and pushed by an earlier run before I started, and the issue was already closed. So there was nothing for me to implement. What I actually did was verify rather than build: re-read the doc against every bullet in the deliverable and the done condition, checked the outbound links from README, docs/agent.md, and the docs index all resolve, confirmed the `warded version` distinction raised in the second comment is covered, and confirmed voice rules pass. It all holds up - the guide is honest up front about the compiled-in owner trust gate and endpoint lock being the real blocker, which is exactly the seam the issue was about. The one thing that gave me pause was FEATURES.md not mentioning the guide, but FEATURES.md is a shipped-feature/subsystem inventory, not a docs index, so a pure doc page correctly does not belong there - adding it would have been noise. High confidence the result matches the ask. Only real follow-up is the pre-existing one the prior run already flagged: #395 will want a guide refresh once the endpoint/owner gate becomes runtime config.

Rows
Columns

No first-run guide connects prerequisites, auth, dry-run, and expected success for warded #467

Why

Deliverable

Done condition