mingchuno · Oct 22, 2026 · Oct 22, 2026
diff --git a/README.md b/README.md
@@ -2,17 +2,53 @@
 
 ![Print-shop workbench with a job sheet, a worked proof, and an inspected copy awaiting human approval.](docs/assets/hero.png)
 
-A local TypeScript SDK and CLI/TUI that turns labelled GitHub or GitLab issues into reviewed change requests with bounded automatic repairs, and reviews existing labelled PRs/MRs. DBOS persists execution; each project uses its existing checkout, with one task at a time. Separate projects progress concurrently.
+A local TypeScript SDK and CLI/TUI that takes engineering work from a sentence or
+an issue to a reviewed change request. One agent skill, `start-work`, is the
+entry point; the CLI enforces policy, records human approval and runs the work
+durably on DBOS. Human review, merging and deployment stay with you.
 
-Supports Codex and Copilot SDKs, GitHub, and GitLab.com/self-hosted GitLab. Human review and merging remain separate.
+Supports Codex and Copilot, GitHub, and GitLab.com/self-hosted GitLab.
 
-Opt-in [adaptive SDLC](docs/engineering/sdlc.md) adds one `start-work` skill and
-deterministic Track A/B/C policy. Track A fixes run inline in the agent session.
-Track B and C work becomes a Work Item with revision-bound human approval, and the
-existing worker executes it.
-See the [task contract](docs/engineering/task-contract.md) for schemas and gates.
+## Quickstart
+
+Prerequisites: Node.js 22.12+, Git, PostgreSQL 17+, a signed-in `codex` or
+`copilot`, and `gh` or `glab`. macOS and Linux are supported.
+
+```sh
+npm install -g @mingchuno/agent-workflows
+npx skills add mingchuno/agent-workflows --skill start-work
+```
+
+Then, in your agent, from the repository:
+
+```text
+$start-work Fix incorrect sorting when size is null     # Codex
+/start-work #123                                         # Copilot
+```
+
+`start-work` classifies the task ([adaptive SDLC](docs/engineering/sdlc.md)):
+
+- **Track A**, a small clear change, runs inline in your agent session and opens
+  the change request. No setup is needed.
+- **Tracks B and C** become a Work Item that waits for your recorded approval of
+  its scope (and design for C), then the worker implements, validates, reviews,
+  repairs and publishes it. The first time, `start-work` offers to set up the
+  repository with you: `agent-workflows init` infers the configuration from the
+  repository and `agent-workflows doctor` names each remaining gap.
+
+Day to day you need two commands:
+
+```sh
+agent-workflows run       # the worker and the web monitor; keep it running
+agent-workflows monitor   # terminal monitor: runs, Work Items and approvals
+```
 
-## When to use it
+Approve gates in the web monitor link `run` prints, or with `a` in the terminal
+monitor. Everything else in `agent-workflows --help` is for the skill or for
+recovery. See the [task contract](docs/engineering/task-contract.md) for schemas
+and gates.
+
+## How it works
 
 DBOS provides durable execution, checkpoints and queues. This SDK supplies the
 coding-workflow behavior a client would otherwise build around it:
@@ -26,53 +62,34 @@ coding-workflow behavior a client would otherwise build around it:
 - **Application controls and evidence:** explicit run outcomes, safe retry
   admission, session/log records, and a shared SDK, CLI, terminal and web monitor.
 
-Clients configure providers and compose operations while DBOS remains responsible
-for durability. [Custom workflows can call DBOS directly](docs/api.md#dbos-sdk-direct-usage).
-Use this SDK when its existing-checkout, one-task-per-project model fits; use DBOS
-directly when you need general-purpose workflows or want to own these policies.
+Each project uses its existing checkout, one task at a time; separate projects
+progress concurrently. [Custom workflows can call DBOS directly](docs/api.md#dbos-sdk-direct-usage).
 
-## Quickstart
+The runner fetches the configured base, creates a branch, implements the work,
+runs the configured checks, and reviews local changes independently. It repairs
+blocking findings or failed checks up to twice with fresh review after each
+repair, then generates publication text, commits once and pushes. Ready results
+create a non-draft PR/MR; unresolved findings, failed checks or incomplete
+inspection create a draft. It never merges. Running the CLI authorizes these
+effects and agent usage.
 
-Prerequisites: Node.js 22.12+, Git, PostgreSQL 17+, and an authenticated Codex or Copilot runtime. macOS and Linux are supported; Windows process-group ownership is not supported.
-
-```sh
-npm install -g @mingchuno/agent-workflows
-createdb agent_workflows
-export AGENT_WORKFLOWS_DATABASE_URL="postgresql://$(id -un)@localhost/agent_workflows"
-agent-workflows init
-```
-
-For SDK use, install `@mingchuno/agent-workflows-core` locally. The CLI and core
-packages share one version and release; the CLI installs its exact matching core
-dependency automatically.
-
-Edit `agent-workflows.json`: set the checkout, hosting origin/repository, agent
-stages and validation commands. Relative checkout, state and prompt-file paths
-resolve from the configuration file's directory. Commits use native Git identity
-and disclose retained writable agent contributions with default-enabled co-author
-trailers. Set the named hosting-token environment variable through your usual
-secret manager; for GitHub, follow the [PAT creation and required permissions](docs/providers.md#create-a-fine-grained-personal-access-token) guide before running. Commit or ignore the configuration before running. Keep the state directory outside managed checkouts, or explicitly Git-ignore it.
-
-```sh
-agent-workflows run
-# Open the printed web monitor URL, or in a second terminal:
-agent-workflows monitor
-agent-workflows status --json
-```
+### Configuration
 
-The local web monitor starts with `run` on port 8787. Use `--no-web` to disable
-it or `--web-port PORT` to change its port. It ships prebuilt with the CLI and
-supports the terminal monitor's inspection and operator actions. See the
-[web monitor guide](docs/operations.md#web-monitor) for access and lifecycle details.
+`agent-workflows.json` holds the checkout, hosting repository, agent, validation
+commands and SDLC policy; see the [configuration reference](docs/configuration.md).
+The CLI uses `gh` or `glab` sign-in for personal projects, or the variable named
+by `hosting.tokenEnv` ([PAT permissions](docs/providers.md#create-a-fine-grained-personal-access-token)).
+Set the database URL in `AGENT_WORKFLOWS_DATABASE_URL`, or keep it with other
+secrets in an [`envFile`](docs/configuration.md#cli-environment-files) outside
+the checkout.
 
-Alternatively, set `"envFile": "./runner.env"` at the top level of
-`agent-workflows.json` to load database, hosting and application variables from
-one explicit file. Existing process values win, including empty strings. See
-[environment file examples and boundaries](docs/configuration.md#cli-environment-files).
+`run` serves the web monitor on port 8787; use `--no-web` or `--web-port PORT`
+to change that. See the [web monitor guide](docs/operations.md#web-monitor).
 
-The runner fetches the configured base, creates a branch, implements an eligible issue, runs optional configured checks, and reviews local changes independently. It repairs blocking findings or failed checks up to twice with fresh review after each repair, then generates publication text, commits once and pushes. Ready results create a non-draft PR/MR; unresolved findings, failed checks or incomplete inspection create a draft. Both deliveries complete the Run. It never merges. Initial use should target a repository and issue you explicitly intend to automate; running the CLI authorizes these effects and agent usage.
+### Label intake and PR/MR review
 
-Enable the standalone review workflow per project with:
+Without SDLC, issues labelled `ready-for-agent` become runs directly. The
+standalone review workflow reviews labelled PRs/MRs:
 
 ```json
 "workflows": {
@@ -92,6 +109,8 @@ queue. See [workflow configuration](docs/configuration.md#workflows).
 ## SDK
 
 Use the SDK when you need to embed the runner or compose a custom workflow.
+Install `@mingchuno/agent-workflows-core` locally; it shares one version and
+release with the CLI.
 It accepts the same project settings as the CLI; your application supplies the
 database URL and loads its own environment.
 

diff --git a/docs/adr/0010-inline-fast-path.md b/docs/adr/0010-inline-fast-path.md
@@ -22,6 +22,8 @@ Investigation, design and knowledge capture become references of `start-work`
 instead of separate skills. Engineers learn one command, and the host loads one
 skill description per session. A separate explicit-only `setup-agent-workflows`
 skill performs onboarding, and `doctor` reports whether delegation is available.
+[ADR 0012](0012-onboard-through-start-work.md) later folded onboarding into
+`start-work`.
 
 Inline Track A work is not enforced by the runner. Team enforcement for it comes
 from repository controls such as CI and protected branches, which also apply

diff --git a/docs/adr/0012-onboard-through-start-work.md b/docs/adr/0012-onboard-through-start-work.md
@@ -0,0 +1,22 @@
+# Onboard through start-work and existing sign-ins
+
+ADR 0010 kept onboarding in a separate explicit-only `setup-agent-workflows`
+skill. In practice an engineer met the gap inside `start-work`, when a Track B
+task found delegation unavailable, and then had to learn a second skill name.
+`init` wrote placeholders the engineer had to replace by hand, and a hosting
+token had to be exported even when `gh` or `glab` was already signed in.
+
+`start-work` is now the only skill. Setup is its reference, offered when
+`doctor` reports a gap for Track B or C work, and it changes nothing without the
+human's agreement. `init` infers the project from the repository instead of
+writing placeholders, and `doctor` reports each gap with its fix. This amends
+ADR 0010's onboarding paragraph; the inline and delegated protocols are
+unchanged.
+
+The CLI reads a missing hosting token from the host CLI's sign-in. That is the
+engineer's own credential, which a same-account agent can already use, so it
+adds no authority for `local-operator` projects. Provider approval relies on
+keeping the approver's credentials apart from the runner's, so those projects
+must opt in with `hosting.tokenFromCli`. The token lands in `tokenEnv` in the
+CLI process only, so redaction and SDLC subprocess filtering treat it like an
+exported token. SDK callers still prepare their own environment.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -15,6 +15,7 @@ documentation.
 - [0009: Separate Work Item authorization from execution](0009-adaptive-sdlc-work-items.md)
 - [0010: Run Track A inline and delegate only gated work](0010-inline-fast-path.md)
 - [0011: Publish clarified contracts to the issue](0011-publish-contracts-to-issues.md)
+- [0012: Onboard through start-work and existing sign-ins](0012-onboard-through-start-work.md)
 
 For observable behavior, see the [public SDK API](../api.md),
 [configuration reference](../configuration.md), and [operator guide](../operations.md).
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -2,11 +2,17 @@
 
 Use this file to define one runner and one or more projects. The CLI reads
 `agent-workflows.json` by default; pass `--config PATH` for another file, or see
-[configuration lookup](#configuration-lookup). Start
-with `agent-workflows init`, then replace the generated repository, checkout,
-agent, and validation values before running it. The file is strict JSON: unknown
+[configuration lookup](#configuration-lookup). The file is strict JSON: unknown
 properties are rejected.
 
+Start with `agent-workflows init` in the repository. It infers the project ID
+from the directory, the host and repository from the `origin` remote, the base
+branch from `origin/HEAD`, the agent from the installed `codex` or `copilot`
+CLI, and the validation command from `package.json` (`verify`, else `test`),
+`Cargo.toml`, `go.mod` or a Makefile `test` target. It enables SDLC with
+`local-operator` approval, prints what it inferred, and marks anything it could
+not discover as a placeholder. Run `agent-workflows doctor` next.
+
 ## Minimal example
 
 This example assumes the file is in the managed repository root. Set the database
@@ -247,8 +253,14 @@ by the previous schema, after stopping the old runner and resolving its work.
 | `origin` | URL string | Web origin, including a GitLab relative root if applicable. |
 | `repository` | nonempty string | Provider repository path, such as `OWNER/REPOSITORY` or `group/project`. |
 | `tokenEnv` | uppercase environment variable name | Variable holding the API token; pattern `[A-Z_][A-Z0-9_]*`. |
-
-All four hosting fields are required. Do not put a token value in the JSON.
+| `tokenFromCli` | boolean | CLI only. When `tokenEnv` is unset, read the token from the `gh` or `glab` sign-in. Defaults to `true` with `local-operator` approval and `false` with provider approval. |
+
+The first four hosting fields are required. Do not put a token value in the JSON.
+The CLI places a token read from `gh auth token` or `glab config get token` in
+`tokenEnv` for its own process only, so the usual redaction and agent
+subprocess filtering apply. Provider approval relies on separating the
+approver's credentials from the runner's, so it needs an explicit opt-in.
+SDK callers prepare their own environment.
 
 ### Agent profile and stages
 

diff --git a/docs/engineering/sdlc.md b/docs/engineering/sdlc.md
@@ -43,35 +43,34 @@ Policy minimums cannot be lowered; change `riskRules` deliberately instead.
 
 ## Set up delegated work
 
-1. Install the skills from the target project with the
+1. Install the skill from the target project with the
    [Skills CLI](https://github.com/vercel-labs/skills), selecting the agent host.
 
    ```sh
-   npx skills add mingchuno/agent-workflows \
-     --skill start-work \
-     --skill setup-agent-workflows
+   npx skills add mingchuno/agent-workflows --skill start-work
    ```
 
-   For unpublished local changes, copy those folders from `skills/` into
+   For unpublished local changes, copy `skills/start-work` into
    `.agents/skills/`. Follow company policy for reviewed, pinned skill
    distribution or an internal mirror.
-2. Invoke `setup-agent-workflows` once per repository. It writes the
-   configuration, prepares PostgreSQL and credentials with you, and verifies
-   them with `agent-workflows doctor`. To do this by hand, follow
-   [provider prerequisites](../providers.md) and keep the state directory
-   outside the source checkout.
-3. Start the resident worker in its own terminal.
+2. Invoke `$start-work` in Codex or `/start-work` in a Copilot host that supports
+   slash invocation, with an issue or a task. When the task needs Track B or C
+   and `agent-workflows doctor` reports a gap, the skill offers to set up the
+   repository with you: it runs `agent-workflows init`, which infers the
+   configuration from the repository, then works through each failing check.
+   To do this by hand, run `init` and `doctor` yourself and follow
+   [provider prerequisites](../providers.md).
+3. Start the resident worker in its own terminal, and approve work in the web
+   monitor it prints or in `agent-workflows monitor`.
 
    ```sh
    agent-workflows run
    ```
 
    Commands find the configuration as described in
    [configuration lookup](../configuration.md#configuration-lookup).
-4. Invoke `$start-work` in Codex or `/start-work` in a Copilot host that supports
-   slash invocation, with an issue or a task. Confirm discovery with that host
-   before relying on it.
 
+Confirm skill discovery with your agent host before relying on it.
 The CLI persists contracts and enforces state transitions. The runner's
 implementation and review stages keep their own prompts. Installing the skills
 does not establish that an SDK-created session loads them.

diff --git a/docs/operations.md b/docs/operations.md
@@ -16,7 +16,8 @@ All commands accept `--config PATH` before the subcommand. For example,
 
 | Command | Effect |
 | --- | --- |
-| `init` | Write a starter config; refuse overwrite |
+| `init` | Write a config inferred from the repository; refuse overwrite |
+| `doctor [--project ID] [--json]` | Check configuration, repository, credentials, host access, agent sign-in, validation commands, database and worker, with a fix for each failure |
 | `version` | Print the installed package version; also available as `--version` or `-V` |
 | `run [--project ID ...] [--no-web] [--web-port PORT]` | Start selected projects and the local web monitor |
 | `config show` | Print merged, schema-validated JSON from the current file without runtime services |

diff --git a/docs/providers.md b/docs/providers.md
@@ -26,6 +26,14 @@ permissions of the local runtime account.
 
 The runner deliberately does not automatically resume interrupted agent work. Runtime session existence does not establish whether old processes are still writing. Use runtime-specific tools/SDKs to inspect sessions after stopping the runner and establishing ownership; there is no universal session-opening command.
 
+## Hosting tokens
+
+Set the variable named by `hosting.tokenEnv`, or sign in with `gh auth login` or
+`glab auth login`. With `local-operator` approval the CLI reads a missing token
+from that sign-in; provider approval needs `hosting.tokenFromCli: true`. See
+[hosting configuration](configuration.md#hosting). `agent-workflows doctor`
+reads the configured repository once to prove the token and repository name.
+
 ## Environment inheritance
 
 CLI `envFile` values reach validation commands, Git subprocesses and agent

diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -5,9 +5,10 @@ web app. Requires Node.js 22.12+ and PostgreSQL.
 
 ```sh
 npm install -g @mingchuno/agent-workflows
-agent-workflows init
-# Configure your checkout, hosting credentials, agent and database.
-agent-workflows run
+npx skills add mingchuno/agent-workflows --skill start-work
+# In your agent: $start-work <task or issue>. It sets up delegated work with you.
+agent-workflows run       # worker and web monitor
+agent-workflows monitor   # terminal monitor and approvals
 ```
 
 The CLI automatically installs the exact matching `@mingchuno/agent-workflows-core`

diff --git a/packages/cli/src/cli-config.ts b/packages/cli/src/cli-config.ts
@@ -6,6 +6,7 @@ import {
   resolveConfiguration,
 } from "@mingchuno/agent-workflows-core";
 import { z } from "zod";
+import { applyCliTokens } from "./hosting-token.js";
 
 const cliConfigurationSchema = configurationInputSchema.extend({
   envFile: z
@@ -32,6 +33,7 @@ export async function openCliConfiguration(
   const { envFile, ...config } = await readConfigurationFile(path);
   if (envFile !== undefined)
     await loadEnvironmentFile(resolveEnvironmentFile(envFile));
+  applyCliTokens(config.projects);
   return {
     config,
     envFile: