squad-kit 0.12.4 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,178 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.1] — 2026-11-03
+
+squad-kit 1.0.1 makes the squad steadier and easier to follow, from what we saw in the first trials. To get it
+from 1.0.0, run `squad upgrade` once. From now on the app updates itself with one button.
+
+### Easier to follow
+
+- **"From an idea or message" works and shows its progress.** The dialog no longer disappears behind a blurred
+  board. The Analyst works in the background with three steps and a clock, and you can press Cancel. You can
+  close the window: the draft waits for you under New ticket.
+- **Errors stay on screen** until you close them.
+- **The Conversation tab reads in plain words.** "Handed in its answer" replaces the raw answer, and a command
+  the step may not run shows in grey as skipped, not in red as a failure.
+- **A ticket waiting for a free place says so**: "Waiting for a free place", with the limit, instead of
+  looking as if it runs.
+- **"Resumed after sleep"** shows when the computer slept in the middle of a step.
+
+### The Update button
+
+- **The app looks for a new version** on start and once a day. When one is out, Home and every project show
+  it with what is new. **Update now** waits until no agent is in the middle of a step, installs, and restarts
+  the app on the same link. Every ticket carries on where it was.
+- **Settings › About squad-kit** shows your version, when it last checked, and a switch for the daily check.
+  Terminal: `squad upgrade`.
+
+### Quality
+
+- **A new Quality setting** on the Squad and AI page: **Best** (the default), **Balanced** or **Thrifty**.
+  On Best, the strongest model builds and reviews at high effort. On Claude Code that is Opus. Terminal:
+  `squad config set quality best`.
+- **A new "extra high" effort.** On Best, a Builder run that fails moves the next one up to extra high.
+- **The Reviewer is never weaker than the Builder** on Best and Balanced.
+- **Reading the project after a merge is cheaper.** The project map is only read again when files are added,
+  moved or removed, and that read runs on a lighter model.
+
+### No silent hangs
+
+- **Stop works at every moment**, also between two runs, and it ends the agent with everything it started. A
+  step that runs out of time ends the same way.
+- **Git that talks to a remote has a time limit**, and never waits for a password prompt nobody sees.
+- **Starting an agent has a time limit.** If it cannot start, the step says why instead of waiting.
+- **The Builder no longer waits for the "before" screenshots.** They are taken beside it, with their own time
+  limit.
+- **A test, lint or build command with no output for 5 minutes is stopped**, and the ticket says which one.
+
+### Agents stay in their lane
+
+- **Every agent runs with the permissions of its step.** The Tester can run the app but cannot change the code;
+  what it changes anyway, squad-kit puts back.
+- **No agent can change the instruction files** the next session would follow, such as `CLAUDE.md`, or
+  squad-kit's own `.squad/` folder. Agents read copies of the project's rules, never your own folder.
+- **No agent can rewrite git history.** squad-kit checks after each Builder and Tester step.
+- **Every answer is checked.** An incomplete answer is asked for once more, then the step says so plainly.
+- **Text from outside**, such as a tracker item or a pasted message, reaches the agents as data, never as
+  orders.
+- **Test, setup and release commands no longer get the AI and tracker keys.**
+
+### No lost work
+
+- **A release and a "Looks right" at the same moment** no longer get in each other's way.
+- **Stop keeps the step the ticket was at.**
+- **"Bring in the latest main"** uses the remote's main, not an old local copy.
+- **Only a real clash counts as a clash.** Other git errors say what went wrong. `squad doctor` checks the git
+  version.
+- **Tracker updates are kept until they are sent**, and retried when the tracker is down.
+- **A release whose push failed** says "not pushed yet", with **Push again** on the Releases page. Terminal:
+  `squad release <version> --push-again`.
+- **Withdraw change** takes back an approved change the squad has not built yet, and puts the spec back to how
+  it was. Terminal: `squad propose <ID> --withdraw`.
+
+### Fixes
+
+- **The Architect writes the stack**, with each part's role, from the code it reads. `stack.md` was empty.
+- **The Reviewer is told the checks already ran**, so it does not run them again.
+
+## [1.0.0] — 2026-11-02
+
+squad-kit 1.0 is an agent harness for the whole software cycle. You write a ticket in plain words. A squad of
+AI agents (Analyst, Architect, Builder, Tester and Reviewer) takes it from that ask to a release, and you stay
+in control through buttons and approvals. It needs Node.js 22 or newer, git, and an AI tool installed and
+signed in: Claude Code today. Moving an existing project: [Moving to 1.0](docs/migrating-to-1.0.md).
+
+### The one app
+
+- **Plain `squad` opens one app for all your projects**, from any folder, in your browser at `127.0.0.1:4571`.
+  It runs on your computer only, behind a private link.
+- **Home** lists your projects and one **Waiting for you** list across all of them.
+- **Add project** opens a folder browser inside the page. It says what kind of folder you picked, and can make
+  a new one.
+- **`squad console`** in a folder adds that project to the app and opens its board, starting the app if needed.
+- Every project has its own board, at its own address. Every button has a terminal command, and commands take
+  `--project <name>` from any folder. New: `squad projects`, and `squad inbox` across every project.
+- `squad --restart` and **Restart the board** start a fresh app on the same link. Running work picks up where it
+  stopped.
+
+### Projects and files
+
+- **Any folder can be a project**: an empty folder (a new repo), code with git (kept as it is), code without git
+  (a new repo with your files in its first commit, without `node_modules`, `dist` or `.env`), or a folder with
+  several code repos.
+- **The project keeps its own memory in `.squad/`**, as Markdown people can read and edit: `config.yaml`, and
+  `tickets/<ID>/` with `ticket.md`, `spec.md`, `questions.md`, `design.md`, `notes.md`, `proof.md` and attached
+  files, plus `decisions/`, `releases/`, `rules/` and `knowledge/`.
+- **This computer keeps its own part in `~/.squad-kit/projects/<id>/`**: live progress, agent chats,
+  screenshots, voice notes, sign-ins and cost. Nothing secret, personal or big goes into the project folder.
+- **Git stays quiet.** `.squad/` goes in git's local ignore list, never in `.gitignore`. For a project whose
+  `.squad/` sits in its one repo, squad-kit commits each ticket's documents on the ticket's branch, and the
+  release commit carries the rest. `git log .squad/tickets/<ID>` shows each big moment of a ticket.
+
+### Tickets and the squad
+
+- **Write a ticket on the board** in plain words, with criteria, business rules, edge cases and files. Or paste
+  an idea or a chat message and the Analyst fills in the ticket for you to check. Bugs have their own form.
+- **Pull a ticket from your tracker.** Azure DevOps today: the backlog by sprint, comments, states, bugs, pull
+  requests on Azure Repos, and items closed with the version on release. Tickets keep the tracker's name, like
+  `AB-46`; a project without a tracker names its own (`LR-1`).
+- **The squad's loop**: questions, spec, design, build, checks, review, proof, release. You answer, approve the
+  spec, approve the design (a developer can do this part), check the proof and release.
+- **Full and Express tracks.** Express is for small fixes: no questions and the plan approved on its own; the
+  build, checks, review and your **Looks right** still run.
+- **squad-kit is the boss.** It runs the tests, lint and build itself, starts a fresh Reviewer, and does the git
+  and tracker work. Agents never merge, push or grade their own work. The Builder works in its own copy of the
+  code; your folder is never touched while it works.
+- **Decisions are saved and linked**, named by the ticket that made them (`AB-46.1`), or `STACK.1` for what the
+  Architect found in the existing code. The Architecture page shows how they build on each other.
+- **Every stop has a way out**: try again, fix it yourself, continue anyway (only you can, with a reason that
+  stays on the record), or go back to the plan. Nothing hangs silently.
+- **Model levels per role and step**: strongest, balanced or fast, with an effort. squad-kit sets the defaults;
+  the team and each person can change them on the Squad and AI page.
+- **One limit of tickets at once** (2 by default, up to 5), shared by all projects, because they share your AI
+  account.
+- AI tools plug in as modules. Claude Code runs every role today; Codex is found but cannot run yet.
+
+### Chat
+
+- **Talk to any agent** on a ticket, with screenshots, files and voice notes.
+- **Asking never stops the work.** While the squad works, the chat runs beside it and changes nothing.
+- **A change goes through the spec.** **Propose a change**: the Analyst writes the old and new wording and says
+  if it is small or big, and you approve. A small change reaches the Builder at the end of its current step. A
+  big one pauses it, the Architect updates the design for your approval, and the Builder redoes only what
+  changed. One change at a time per ticket. Terminal: `squad propose`.
+- **Released work is for questions only.** A change to it becomes a new linked ticket or a bug report.
+- A new chat window is coming in this release: a side panel with tabs, a full-screen page, a phone layout, and
+  Arabic and English shown the right way.
+
+### Teams
+
+- **An owner on each ticket**, kept in `ticket.md`, so two squads never build the same ticket.
+- **Hand over** (button and `squad hand-over`) pushes the ticket's branch with its code and documents, and names
+  the new owner. Their squad carries on from the branch, with a fresh session from the spec, design and code.
+- **A fresh clone shows the same board**: every ticket with its spec, answers, design, stage and owner, and
+  every decision. Live progress, chats and screenshots stay on the computer that made them.
+- Hand over and clones work for a project whose `.squad/` sits in its one repo.
+
+### Cost
+
+- **What each ticket and each role used**: runs, tokens, and the cost at the AI company's API prices, per role
+  and step. On the ticket's Cost tab, the Squad and AI page, the board's footer and in `squad show`.
+- Your own AI subscription pays for it. The numbers show where the cost goes, so the team can tune the levels.
+
+### Moving from 0.x
+
+- **Open a 0.x project** with `squad console` or Add project. Its `stories/`, `plans/` and tracker settings in
+  `config.yaml` stay as they are; `config.yaml` gains a `board:` section.
+- **Sign-ins move** from `.squad/secrets.yaml` to `~/.squad-kit/projects/<id>/secrets.yaml`. The 0.x commands
+  find them there.
+- **A board from an early 1.0 build** (`.squad/board/`) moves to the new layout on its own, once, with a backup
+  in `~/.squad-kit/backups/` and a field-by-field check. Tickets and decisions keep their names. It waits until
+  no board runs.
+- The 0.x commands (`new-story`, `new-plan`, `auth`, `config`, `doctor` and others) still ship. The 0.x console
+  pages are replaced by the 1.0 app.
+
 ## [0.12.4] — 2026-08-26
 
 ### Bug fixes
@@ -631,7 +803,9 @@ First public release.
 - Plan-generation meta-prompt (`generate-plan.md`), intake template (`intake.md`), and plan skeleton reference (`story-skeleton.md`).
 - Documentation: `docs/philosophy.md`, `docs/getting-started.md`, `docs/customization.md`, `docs/vs-spec-kit.md`.
 
-[Unreleased]: https://github.com/AzmSquad/squad-kit/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/AzmSquad/squad-kit/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.0.1
+[1.0.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.0.0
 [0.6.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v0.6.0
 [0.5.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v0.5.0
 [0.3.0]: https://github.com/AzmSquad/Squad-Kit/releases/tag/v0.3.0

package/README.md

@@ -11,274 +11,164 @@
   <a href="https://squad-kit.com"><img src="https://img.shields.io/badge/site-squad--kit.com-7cffa0?labelColor=0a0a0c" alt="Website"></a>
 </p>
 
-**Plan once, execute cheap.** A 3-step SDD-style workflow CLI for AI-assisted coding: **raw story → good plan → implementation**. Your expensive model plans once. A cheap model executes many times. Squad-kit owns the folder conventions, the plan meta-prompt, and the agent slash-commands so the token cost goes where it pays off. Deeper product notes live on **[squad-kit.com](https://squad-kit.com)** and in [`docs/`](docs/philosophy.md).
+**Your AI Engineering Squad. One Unified Harness.**
 
-- **Visual console** — `squad console` opens a local, dark-modern web UI for stories, plans, live planner runs, config, secrets, tracker, and doctor. Loopback-only, token-gated. v0.6.0 redesigned the console with a near-monochrome Vercel/Geist palette, a Cmd+K command palette, Linear-style chord shortcuts (`g s`, `g p`, `?`), a portal-rendered dialog system, and a density toggle. Full tour: [`docs/console.md`](docs/console.md).
+squad-kit is an agent harness for the whole software cycle. You describe what you need in plain words. A
+squad of AI agents takes it from that ask to a release: the Analyst, the Architect, the Builder, the Tester
+and the Reviewer. You stay in control. The squad asks you when it needs you, and nothing important moves on
+without your approval.
 
-![Squad console dashboard](docs/images/console/dashboard.png)
+## Who it is for
 
-```
-.squad/
-├── stories/<feature>/<id>/  # intake + attachments (one per story)
-└── plans/<feature>/         # NN-story-<id>.md (one per executable plan)
-```
-
-## What's new in 0.12.0
-
-- **Plan on your Claude subscription.** `squad auth login` signs in with your Anthropic account and `squad new-plan --api` runs on your Claude plan — no API key, no per-token API bill. Usage draws on the same limits as Claude and Claude Code. Full guide: [`docs/auth.md`](docs/auth.md) · [on the site](https://squad-kit.com/docs/auth).
-- **`planner.auth.anthropic`** — `subscription` | `api-key` | `auto` (default `auto`). Existing API-key workspaces keep working; `squad doctor` gained `planner auth mode` and `planner auth vs. runtime` so the resolved mode is never a mystery.
-- **Console auth surface** — an Authentication control on Config, a Claude Account card on Secrets, an auth badge on Generate and on every run record.
-
-## What's new in 0.11.0
-
-- **Persisted run history** — `--api` runs append to `.squad/runs/<id>.events.jsonl` (thinking text redacted on disk, old files rotated), and the console gained a runs index plus a full run report page.
-- **Richer live telemetry** — tool lifecycle, thinking deltas, and runtime metadata stream to both the CLI and the console; the CLI prints a stage pipeline and budget meters.
-
-## What's new in 0.10.0
-
-- **Anthropic planning moved to the Claude Agent SDK** by default so Opus 4.7 can use adaptive thinking and effort. OpenAI and Google stay on the Vercel AI SDK.
-- **Thinking, effort, and runtime are configurable** — `planner.runtime.anthropic`, `planner.providerOptions.anthropic`, and the `--anthropic-runtime` / `--effort` / `--scout-effort` / `--no-thinking` flags.
-- **`squad doctor` checks runtime wiring**, model-vs-runtime fit, and the Agent SDK binary.
-
-## What's new in 0.9.0
-
-- **Scout stage** — a cheap-tier model picks the files worth preloading before your plan model drafts, cutting the expensive model's read loop.
-- **LLM-free validation pass** flags missing paths, line ranges past EOF, and simple symbol problems; `--strict-validation` writes `*.partial.md` when it finds something.
-
-## What's new in 0.8.0
-
-- **Rate-limit handling you can watch** — the Generate page shows a countdown, auto-retry banner, and rerun control; the planner emits `rate_limit` events distinguishing "retrying" from "aborted".
-
-## What's new in 0.7.0
+- **Business analysts and project managers** who want to turn tickets into working software, and always see
+  where each ticket is. No terminal skills needed after the first step.
+- **Developers** who want the squad to do the routine work, while they approve designs and read the code.
+- **Teams** who want specs, decisions and releases kept with the project, in files anyone can read.
 
-- **GitHub Issues as a tracker** — owner/repo in config, PAT (or `GITHUB_TOKEN`) in secrets, search and import like Jira or Azure. **Linear was removed** as a tracker type in the same release.
+## How a ticket goes
 
-## What's new in 0.6.0
+1. You write a ticket on the board, or pull one from your tracker (the tool where your team keeps its work
+   items).
+2. The Analyst asks you questions. You answer with a click.
+3. The Analyst writes the **spec**: the story and a "done when" list. You approve it.
+4. The Architect writes the **design**: the decision and the steps. You, or a developer, approve it.
+5. The Builder writes the code in its own copy of the project. Your own folder stays as it is.
+6. squad-kit runs the tests, lint and build itself. The Reviewer checks the work with fresh eyes. The Tester
+   takes a screenshot for each "done when".
+7. You check this **proof** and press **Looks right**.
+8. You press **Release**. squad-kit writes the changelog, sets the version and adds the git tag.
 
-- **Console redesign** — Geist-style flat dark UI, Cmd+K command palette, global keyboard shortcuts, portal dialogs, density toggle. Same CLI and `.squad/` on disk; no migration. See [`docs/console.md`](docs/console.md).
-
-## What's new in 0.5.0
-
-- **`squad console`** — local web UI on `127.0.0.1:4571` for the whole workflow (dashboard with run charts, stories, plans + diff, live Generate SSE, config/secrets editors, tracker search/import, graphical doctor). See [`docs/console.md`](docs/console.md).
-- **Run history** — last 20 planner runs under `.squad/runs/` power dashboard charts; **recent projects** list in `~/.squad/recent-projects.json` for quick handoff between repos.
-- **`pnpm size:guard`** — publish tarball must stay under 2.5 MB unpacked.
-
-## What's new in 0.4.0
-
-- **`squad new-plan --api` limits UX.** When a budget or cap stops the planner, the CLI asks before more API spend. Stop saves a `*.partial.md` with a clear status flag; exit code **2** when the run did not finish cleanly.
-- **`planner.maxOutputTokens`** in merged config (default **16384** tokens per model round).
-- **Shorter plan filenames** — new plans use the story folder id (`NN-story-<id-slug>.md`), not a long title slug; the overview table still shows the title.
-- **Richer intakes** when `squad new-story` fetches Jira / Azure work items (more fields wired into the template).
-- **`squad list`** reads `<!-- squad-kit: … -->` metadata from the first matching line near the top of a plan file, not only line 1.
-
-## What's new in 0.3.0
-
-- **Prompt caching** across Anthropic, OpenAI, and Google — ~70% fewer billed input tokens on
-  a typical planning run, and Anthropic Tier 1 ITPM pressure roughly 5× lower.
-
-## What's new in 0.2.0
-
-- **Direct planner.** `squad new-plan --api` runs Anthropic, OpenAI, or Google from your terminal and writes the plan file. Demand-driven context keeps tokens bounded.
-- **Tracker auto-fetch.** `squad new-story --id <ID>` pulls title, description, labels, and attachments (≤ 10 MB each) from Jira Cloud or Azure DevOps Services.
-- **Secrets split.** API tokens live in `.squad/secrets.yaml` (git-ignored, `0600` on POSIX). `.squad/config.yaml` never holds secrets; the loader rejects secret-shaped keys.
-- **Interactive-first UX.** Missing input prompts in a TTY; `-y` / `--yes` or `CI=1` opts out and fails fast.
-- **`squad doctor`.** Full read-only health check; `--fix` for non-destructive repairs, `--json` for scripting.
-- **`squad migrate`.** One-shot 0.1.x → 0.2.0 structural migrations (delete legacy `.squad/prompts/`, permissions, config normalisation). Destructive; use `--dry-run` first.
-- **`squad upgrade`.** Safe npm-backed self-update (`--check` to verify only).
-- **`squad config`.** `show`, `set planner` / `set tracker`, `unset …`, `remove-credential …` — edit config and secrets without hand-editing YAML.
-- **`squad rm`.** `rm story` / `rm plan` / `rm feature` with `--dry-run`, `--trash`, and cascading overview updates.
-- **Bundled prompts.** `generate-plan.md`, `intake.md`, and `story-skeleton.md` ship inside the npm package; upgrade the CLI to update them.
-
-Full list in [`CHANGELOG.md`](CHANGELOG.md).
-
-## Upgrading from 0.1.x
-
-Existing squad-kit users should run two commands, once per repo:
-
-```bash
-pnpm add -g squad-kit             # or: npm install -g squad-kit — or: squad upgrade
-cd your-project && squad migrate
-```
+When the squad needs you, a card shows up in **Waiting for you**. Everything else, the squad handles. Every
+button also has a terminal command, so developers can do the same from the terminal.
 
-`squad migrate` deletes the now-unused `.squad/prompts/` directory, appends the managed `.gitignore` block, tightens `.squad/secrets.yaml` permissions to `0600`, and normalises `.squad/config.yaml`. It is idempotent but destructive — run it with `--dry-run` first if you forked the prompt files.
+## What you need
 
-Full upgrade walkthrough, including what-if scenarios and how to recover customised prompts: [migration guide (repo)](docs/migrating-from-0.1.md) · [migration guide (site)](https://squad-kit.com/docs/migrating-from-0.1).
+- **Node.js** 22 or newer.
+- **git**.
+- **An AI tool**, installed and signed in once with your own account. Today that is **Claude Code**, the only
+  AI tool the squad runs on. squad-kit uses your existing sign-in, so there is nothing new to buy. squad-kit
+  also finds Codex, but cannot run it yet.
 
 ## Install
 
 ```bash
-npm install -g squad-kit
-# or
-pnpm add -g squad-kit
+npm i -g squad-kit
 ```
 
-Requires Node 18+.
-
-## Quickstart
+## Open squad-kit
 
 ```bash
-cd your-project
-squad init                                              # interactive: tracker, planner, agents, name
-squad new-story auth --title "SSO support"              # or: squad new-story auth --id ENG-42 to auto-fetch
-# → edit .squad/stories/auth/ENG-42/intake.md
-
-/squad-plan .squad/stories/auth/ENG-42/intake.md        # in your agent (Claude / Cursor / Copilot / Gemini)
-# → .squad/plans/auth/01-story-sso-support.md
-
-# new agent chat · attach ONLY the plan file · a cheap model ships it
+squad
 ```
 
-No slash commands in your agent? Skip the meta-prompt copy-paste entirely:
+This opens squad-kit in your browser. It runs on your computer only, at `127.0.0.1:4571`. It is one app for
+all your projects:
 
-```bash
-squad new-plan --api   # interactive picker, direct provider call, writes the plan file
-```
+- **Home** lists your projects, and one **Waiting for you** list for all of them.
+- Each project has its own **board**, with its tickets in columns, from a new ticket to its release.
+
+Keep the terminal open while you work. Press Ctrl-C there to stop squad-kit. The squad picks up where it was
+the next time you run `squad`.
 
-### Plan on your Claude subscription
+## Add a project
 
-If you already pay for **Claude Pro or Max**, you do not need an Anthropic API key to use the direct planner:
+On Home, press **Add project** and pick a folder in the folder browser. Or open a terminal in the folder and
+run:
 
 ```bash
-squad init             # choose Anthropic, then "Use my Claude subscription (browser login)"
-squad auth login       # browser sign-in; or just run `claude` and use /login
-squad new-plan --api   # plans on your Claude plan
+squad console
 ```
 
-**No API key is needed** on this path. Planning usage draws on your **Claude plan's usage limits** — the same limits Claude and Claude Code consume — so there is no per-token API bill, but a long planning run does consume part of your window. Opus planning against a **Pro** plan drains that window noticeably faster than against **Max**.
-
-Already signed in to Claude Code? squad-kit picks that login up automatically. Prefer an API key? Nothing changed — set `planner.auth.anthropic: api-key`. Details, CI setup, precedence, and troubleshooting: [`docs/auth.md`](docs/auth.md) · [on the site](https://squad-kit.com/docs/auth).
+Any folder works:
 
-Configuration, credential edits, and non-interactive flags: see [`docs/customization.md`](docs/customization.md) and `squad config show`. Full walkthrough: [`docs/getting-started.md`](docs/getting-started.md).
-
-## Commands
-
-| Command | What it does |
+| The folder | What squad-kit does |
 | --- | --- |
-| `squad init` | Scaffold `.squad/` with config, bundled prompts reference, and agent slash-commands. See [`docs/getting-started.md`](docs/getting-started.md). |
-| `squad new-story [feature] [--id ID] [--title …] [--no-tracker] [--no-fetch] [--no-attachments] [--attachment-mb n]` | Create a story intake. Auto-fetches from the configured tracker when `--id` is given. |
-| `squad new-plan [intake] [--api] [--copy] [--feature <slug>] [--all]` | Generate a plan from an intake. `--api` calls the configured planner; without `--api`, copy-paste mode prints the prompt to stdout and clipboard (`--no-clipboard` to skip the clipboard). |
-| `squad status` | Counts, next `NN`, planner and tracker rows (including credential source). |
-| `squad list [--feature <slug>]` | Table of stories and plan state. |
-| `squad tracker link [story] [id]` | Attach or update a tracker id on an intake. |
-| `squad auth <login\|status\|logout>` | Sign in to Anthropic with your Claude subscription, inspect the resolved auth, or clear the stored token. `login` takes `--token <v>` (CI) and `--print-only`; `status` takes `--json` and `--offline`. See [`docs/auth.md`](docs/auth.md) · [site](https://squad-kit.com/docs/auth). |
-| `squad config <show\|set\|unset\|remove-credential> …` | View and edit `.squad/config.yaml` and `.squad/secrets.yaml` interactively. See [`docs/customization.md`](docs/customization.md). |
-| `squad rm <story\|plan\|feature> [target] [--dry-run] [--trash] [-y]` | Safely delete with cascading overview updates. |
-| `squad doctor [--fix] [--json]` | Full health check; `--fix` applies non-destructive repairs. |
-| `squad migrate [--dry-run] [-y]` | One-shot 0.1.x → 0.2.0 structural migrations. Destructive. |
-| `squad upgrade [--check] [-y]` | Check npm and install a newer squad-kit release. |
-| `squad console [--port n] [--no-open]` | Start the loopback web console; see [`docs/console.md`](docs/console.md). |
-
-Deeper option lists: `squad <command> --help` and the `docs/` pages above.
-
-## Direct planner (optional)
-
-Off by default. Enable during `squad init` (answer **yes** to *Enable automatic plan generation?*) or later with `squad config set planner`. Supported providers: Anthropic, OpenAI, Google.
-
-### Credential resolution order
-
-**Anthropic — default: your Claude subscription**
+| An empty folder | Makes a new git repo. The Architect picks the stack with you on your first ticket. |
+| Code with git | Keeps your repo and its history as they are. |
+| Code without git | Makes a repo, with your files in its first commit. Generated folders like `node_modules` and `dist`, and `.env` files, stay out. |
+| A folder with several code repos | Works across them. Each ticket works in one repo. |
+| A squad-kit 0.x project | Keeps your stories, plans and tracker settings. Moves your sign-ins to this computer. |
 
-1. **`planner.auth.anthropic`** in `.squad/config.yaml` — `subscription` | `api-key` | `auto` (merged default: **`auto`**).
-2. **`subscription`** — the login created by `squad auth login` (or `claude` → `/login`), resolved in this order:
-   `CLAUDE_CODE_OAUTH_TOKEN` → `planner.anthropicOauthToken` in `.squad/secrets.yaml` → the OS credential store (macOS Keychain / `~/.claude/.credentials.json`).
-3. **`api-key`** — `ANTHROPIC_API_KEY` → `SQUAD_PLANNER_API_KEY` → `.squad/secrets.yaml`.
-4. **`auto`** — a detected Claude login first, otherwise the API key chain, otherwise fail naming both recovery paths.
+Then the Architect reads the project, which takes a few minutes. It maps the code and finds how to install,
+test, build and run it. You can follow it on the board.
 
-In subscription mode squad-kit **clears `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` from the planner subprocess** (your shell is untouched): both outrank the login credential inside Claude Code, so an inherited one would silently bill API credits instead. If you have a key exported and it is being ignored, that is why.
+## Your first ticket
 
-`auth: subscription` requires the Agent SDK runtime — `planner.runtime.anthropic: vercel` is a hard, early failure, never a silent downgrade.
+1. On the board, press **New ticket**.
+2. Write what you want in plain words. Add business rules, examples or screenshots if you have them. Or paste
+   an idea or a chat message, and the Analyst fills in the ticket for you to check.
+3. Press create. The card moves across the board as the squad works.
+4. Answer, approve and check when a card shows up in **Waiting for you**.
 
-**OpenAI / Google — API key only, unchanged**
+The step-by-step guide is in [Getting started](docs/getting-started.md).
 
-1. Provider env var (`OPENAI_API_KEY`, `GOOGLE_API_KEY`).
-2. `.squad/secrets.yaml` under `planner.<provider>` (or cross-provider `SQUAD_PLANNER_API_KEY`).
-3. Interactive prompt (TTY only).
-4. Fail with a recovery hint.
+## Where your files live
 
-The deep page — both login paths, per-platform credential storage, CI, usage limits, and a troubleshooting table — is [`docs/auth.md`](docs/auth.md), also served at [squad-kit.com/docs/auth](https://squad-kit.com/docs/auth).
+squad-kit keeps files in two places. The test is simple: does another person need it to carry on?
 
-Override the default plan-phase model without editing squad-kit:
+**Yes: in the project folder, in `.squad/`.** This is the project's memory. It is plain Markdown and YAML that
+people can read and edit.
 
-```yaml
-planner:
-  enabled: true
-  provider: anthropic
-  auth:
-    anthropic: subscription   # or api-key, or auto (default)
-  cache:
-    enabled: true   # default; turn off via squad config set planner
-  modelOverride:
-    anthropic: claude-opus-5-0      # riding a newer provider release early
+```
+.squad/
+  config.yaml        the project's settings
+  tickets/AB-46/     one folder per ticket: ticket.md, spec.md, questions.md,
+                     design.md, notes.md, proof.md, and files people attached
+  decisions/         what the squad decided, and why: AB-46.1.md, STACK.1.md
+  releases/          what each release carried
+  rules/             house rules for each role
+  knowledge/         what the squad learned about the project
 ```
 
-`squad status` marks the planner row `(override)` when a `modelOverride` is active, and shows a **planner auth** row with the resolved mode. `squad doctor` probes the provider's `/v1/models` endpoint (no paid completion) and tells you what to do if the id is no longer served — that probe and the API rate-tier check both **skip on subscription auth**, since there is no API key to list models with and no API rate tier to warn about.
-
-Slash commands inside your agent (`/squad-plan`) continue to work unchanged — the agent already has your repo in scope. The direct planner is an alternative path, not a replacement. For where keys live, see [Secrets](#secrets) below and [`docs/customization.md`](docs/customization.md).
-
-## Tracker auto-fetch
-
-`squad new-story <feature> --id <ID>` pulls the work item's title, description, labels, and attachments (≤ 10 MB each) straight into the intake. Supported trackers in 0.2.0: **Jira Cloud**, **Azure DevOps Services**.
-
-Credentials follow the same resolution order as the planner (env → `.squad/secrets.yaml` → prompt → fail). `squad init` prompts for them when a supported tracker is selected.
-
-Flags:
-
-- `--no-fetch` — scaffold an empty intake; never call the tracker.
-- `--no-attachments` — fetch metadata only.
-- `--attachment-mb <n>` — override the 10 MB per-file cap.
-- `--no-tracker` — skip the tracker id requirement for this story even when `naming.includeTrackerId: true`.
-
-Full example with Azure DevOps: [`docs/getting-started.md`](docs/getting-started.md).
-
-## Secrets
-
-squad-kit stores settings in two files:
-
-| File | Purpose | Git-tracked? | Editable by hand? |
-| --- | --- | --- | --- |
-| `.squad/config.yaml` | Project name, tracker, naming, agents, planner shape. | yes — commit it | yes, but `squad config set` is safer |
-| `.squad/secrets.yaml` | Planner + tracker API tokens, and the Claude OAuth token (`planner.anthropicOauthToken`). | **no** — auto-ignored, `0600` on POSIX | no — use `squad auth login` / `squad config set` / `squad init` |
-
-`config.yaml` rejects credential-shaped key names at load time — `apiKey`, `api_key`, `token`, `oauthToken`, `anthropicOauthToken`, `secret`, `credential`, `credentials` — so accidental commits fail loud. Matching is on the **exact lowercased key name**, not a substring: a substring rule would reject the legitimate `planner.maxOutputTokens`. Any future credential-shaped key has to be added to that list by name.
+**No: on this computer, in `~/.squad-kit/`.** Live progress, agent chats, screenshots, sign-ins (tokens) and
+cost belong to you and this computer. They never go into the project folder.
 
-Rotate a credential with `squad config set planner` or `squad config set tracker`; remove one with `squad config remove-credential <section>`. `squad auth logout` removes only the Claude OAuth token squad-kit stored and never touches your global Claude Code login.
+For a project whose `.squad/` sits inside its code repo, squad-kit commits each ticket's documents on the
+ticket's own branch, so they reach `main` with the code. `.squad/` stays out of your own `git status`.
 
-## Why not Spec-Kit?
+## Work with your team
 
-Both aim at spec-driven development. They make different bets.
+- **Tracker.** Connect your tracker in Settings, then pull work items onto the board. Tickets keep the tracker's
+  name, like `AB-46`. squad-kit moves the item along as the squad works, posts the answers and the plan as
+  comments, and opens a pull request for each finished ticket. Today this works with **Azure DevOps** (Azure
+  Boards and Azure Repos).
+- **Hand over.** Give a ticket to a teammate with **Hand over**. squad-kit pushes the ticket's branch with its
+  code and documents, and names the new owner. Their squad carries on from there.
+- **A new computer or a new teammate.** Clone the project and add it. The board comes back from `.squad/`:
+  every ticket with its spec, answers, design, stage and owner, and every decision.
 
-| | squad-kit | Spec-Kit |
-| --- | --- | --- |
-| Commands | `init`, `new-story`, `new-plan`, `status`, `doctor`, `migrate`, `upgrade`, `list`, `rm`, `tracker link`, `auth`, `config` | `constitution`, `specify`, `clarify`, `plan`, `tasks`, `analyze`, `checklist`, `implement` |
-| `/implement` turn starts with | one plan file (~5–15 KB) | 5–7 command templates + cross-artifact reads (~15–25 KB) |
-| Model-tier awareness | Built into the philosophy (planner ≠ executor) | Not prescribed |
-| Generated artifacts per story | `intake.md`, `NN-story-<id>.md`, overview row | `spec.md`, `plan.md`, `data-model.md`, `contracts/`, `research.md`, `quickstart.md`, `tasks.md` |
-| Customization | Prompts ship with the CLI (fork squad-kit to change them). | Template override stack with presets/extensions |
-| Runtime | Node + TypeScript, npm-distributable | Python + `uv` |
-| Scope | Intentionally small | Broad, with safety nets (`clarify`, `analyze`) |
+Hand over and clones work for a project whose `.squad/` sits in its one code repo.
 
-Spec-Kit ships safety rails. Squad-kit ships the cheap path and gets out of the way. Pick squad-kit when your planner already produces trustworthy plans; pick Spec-Kit when you want the process to catch planning mistakes for you.
+## Talk to the squad
 
-See [`docs/philosophy.md`](docs/philosophy.md) for the token math and [`docs/vs-spec-kit.md`](docs/vs-spec-kit.md) for the full comparison.
+Open a chat with any agent on a ticket. **Asking never stops the work**: the squad keeps working while you
+talk. To change what gets built, press **Propose a change**. The Analyst writes the change into the spec, old
+and new side by side, and you approve it. A released ticket answers questions only. A change to it becomes a new
+linked ticket or a bug report.
 
-## Tradeoffs to know
+## Cost and models
 
-- **Quality depends on the planning model.** squad-kit has no safety-net commands. Use a strong model for `new-plan`.
-- **Plans are project-coupled.** They reference real file paths. That is the point — do not expect portability between projects.
-- **Global `NN` can collide on parallel branches.** Rebase-and-renumber is the resolution. Documented in [`docs/customization.md`](docs/customization.md).
-- **Anthropic Tier 1 + Opus** shares a tight input-token-per-minute bucket. **0.3.0** added prompt caching (on by default) so typical multi-turn plans stay viable; see [Prompt caching](docs/customization.md#prompt-caching) in the customization docs.
-- **Subscription planning is not free planning.** It removes the per-token API bill, not the cost: Agent SDK usage draws on your Claude plan's usage limits. Opus planning on **Pro** will exhaust a window much faster than on **Max**. See [`docs/auth.md`](docs/auth.md).
+- squad-kit picks a **model level** for each role and step from the project's **Quality** setting: **Best**
+  (the default) builds and reviews on the strongest model, **Balanced** builds on it at medium effort, and
+  **Thrifty** builds on a lighter one. **Fast** stays for screenshots and small helpers. The team or each person
+  can change single steps on the **Squad and AI** page.
+- The board shows **what each ticket and each role used**, in tokens and in money at the AI company's API
+  prices. Your own AI subscription pays for it. This shows where the cost goes.
+- One **limit of tickets at once** (2 by default, up to 5) is shared by all your projects, because they use the
+  same AI account.
 
-## Non-goals for 0.2
+## Docs
 
-We ship lean on purpose. Current non-goals:
+- [Getting started](docs/getting-started.md): your first hour, from install to a release.
+- [Moving to 1.0](docs/migrating-to-1.0.md): from squad-kit 0.x, and from early 1.0 boards.
+- [The app](docs/console.md): Home, the board, the ticket drawer, Squad and AI, and Settings.
+- [CHANGELOG](CHANGELOG.md): what changed in each version.
 
-- OpenAI-compatible generic endpoint (local models, OpenRouter, etc.); [Direct planner (optional)](#direct-planner-optional) covers hosted Anthropic, OpenAI, and Google
-- MCP server
-- `squad implement` (future release)
-- `/clarify`, `/analyze`, constitution-equivalent
-- Telemetry
+The 0.x planner commands (`squad new-story`, `squad new-plan`, `squad auth` and others) still ship. Their docs
+are kept as they were: [auth](docs/auth.md), [customization](docs/customization.md),
+[philosophy](docs/philosophy.md), [squad-kit vs Spec-Kit](docs/vs-spec-kit.md) and
+[migrating from 0.1](docs/migrating-from-0.1.md).
 
 ## License
 
-MIT. Contributions welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+MIT. Contributions welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md).