docs: refactor README for newcomers (developer and non-developer)

[gcko]

Summary

Replaces the developer-leaning README.md with a five-document set designed around two questions a first-time reader actually has:

1. What is this?
2. How do I use it?

The current README assumes the reader is already comfortable with Claude Code, the Star Trek metaphor, and pasting shell strings. Spacedock is general purpose: it works just as well for email triage, trip planning, tax prep, content publishing, household admin, research synthesis, and job search as it does for PR review and ticket-shipping. The new docs broadcast that range up front while still serving the developer audience.

What's in the PR

• README.md rewritten: short, leads with non-developer scenarios, Star Trek metaphor introduced once with plain-English equivalents, five-minute quick start with a realistic timeline.
• docs/GETTING_STARTED.md: two end-to-end walkthroughs (email triage and pull request review) with first-gate output, approval flow, rejection with feedback, and /spacedock:debrief. Inline glossary at the top so readers do not need to bounce to USAGE first.
• docs/USAGE.md: mental model and YAML schema reference. Full stage flag table with defaults (initial, gate, worktree, concurrency, fresh, feedback-to, parked, terminal, agent, model). New "Cost, data, and recovery" section covering the safety questions a non-developer needs answered before pointing Spacedock at their inbox.
• docs/EXAMPLES.md: eight worked examples spanning household, knowledge work, and development. Each has audience, recurring pain, mission string, stage table with flags, and what success looks like after two weeks of use.
• docs/PROMPTS.md: fill-in-the-blank Initiating Prompt template plus six persona variants (developer, email triager, trip planner, household and finance, content creator, researcher) so a prospective user can have Claude read Spacedock and propose workflows shaped to their actual work.
• docs/superpowers/specs/2026-05-20-readme-refactor-newcomer-friendly.md: the spec the work was built against.

How it was made

Five writer agents drafted the five docs in parallel against a shared spec and style guardrails. Then four rounds of reviewer agents audited the result. The round 3 and 4 reviewers were framed adversarially: docs guilty until proven innocent, prior rounds too kind. Lenses applied:

• Clarity and time-to-value for both audiences.
• AI-language hygiene (zero em-dashes, no banned filler like tailored, robust, seamless; no reflexive paragraph openers; no closer-line syndrome).
• Technical accuracy against skills/, mods/, the status binary, and the test fixtures.
• Cross-document flow and post-edit consistency.
• Hostile newcomer edge cases (Windows, Workspace admin restrictions, OAuth scopes, mistake recovery, cost, kill switch, multi-workflow).
• Mission-string commission-parse audit: do mission strings actually generate the YAML the docs claim, and are there entity-label derivation bugs (yes; fixed).
• Source-code archaeology: hunting for flags, behaviors, and defaults the docs misrepresent.

Each round surfaced real issues the prior round missed. A few of the more interesting fixes:

• redirect is not a real gate response. The runtime accepts approve | reject only. Removed everywhere; the "edit then approve" path is now spelled out as a distinct option.
• parked: true has no enforcement in the runtime. Documented as a captain-facing convention with explicit "the captain or a mod is what advances" framing in every example.
• concurrency only governs worktree-bearing dispatches; described with the actual semantics.
• The "First Officer reads the workflow on every loop" claim was wrong (read once at boot; hand-edits take effect on next session). Corrected in four places.
• pr-merge mod only advances to terminal at PR merge; EXAMPLES previously claimed it advanced between arbitrary stages. Fixed.
• Entity-label derivation bugs in mission strings: "a batch of up to 50 emails" would generate entity-label: emails with plural emailss. Reworded to produce sane labels.
• Terminology drift: antagonistic (EXAMPLES) vs adversarial (README, USAGE). Standardized on adversarial.

Style guardrails enforced

• Zero em-dashes anywhere. No en-dashes used as separators. ASCII quotes only.
• No emoji in body copy. No -> arrows where the word to works.
• Sentence-case headings. Banned filler vocabulary swept across all five docs.
• Star Trek terms (Captain, First Officer, Ensign) introduced once in the README with their plain-English equivalents in parentheses, then used freely.

Test plan

• Read README cold; confirm a non-developer can answer "what is this?" in 30 seconds.
• Walk through docs/GETTING_STARTED.md walkthrough 1 (email triage) end to end on a machine with gws-cli configured.
• Walk through walkthrough 2 (PR review) end to end on a developer machine.
• Spot-check three EXAMPLES mission strings: paste each into a fresh Claude Code session and verify the generated workflow matches the table description.
• Paste the developer PROMPTS variant; verify Claude's proposals include feedback-to: on bouncing gates as instructed.
• Verify cross-references between the five docs resolve to existing files.