@gh-symphony/cli 0.0.17 → 0.0.19

package/README.md

@@ -8,10 +8,15 @@ The following tools must be installed before using the CLI:
 
 - **[Node.js](https://nodejs.org/)** (v24+) with npm
 - **[Git](https://git-scm.com/)**
-- **[GitHub CLI (`gh`)](https://cli.github.com/)** — authenticated with required scopes:
-  ```bash
-  gh auth login --scopes repo,read:org,project
-  ```
+- One GitHub auth source with required scopes (`repo`, `read:org`, `project`):
+  - **[GitHub CLI (`gh`)](https://cli.github.com/)**:
+    ```bash
+    gh auth login --scopes repo,read:org,project
+    ```
+  - Or `GITHUB_GRAPHQL_TOKEN` for CI or minimal shells:
+    ```bash
+    export GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token
+    ```
 
 ## 1. Install Package
 
@@ -25,6 +30,15 @@ Verify the installation:
 gh-symphony --version
 ```
 
+Validate the machine and repo prerequisites before first use:
+
+```bash
+gh-symphony doctor
+gh-symphony doctor --fix
+gh-symphony doctor --json
+GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token gh-symphony doctor --json
+```
+
 Enable shell completion:
 
 ```bash
@@ -44,19 +58,34 @@ autoload -Uz compinit && compinit
 Navigate to the repository you want to orchestrate, then run:
 
 ```bash
-gh-symphony init
+gh-symphony workflow init
+gh-symphony workflow init --dry-run
+gh-symphony workflow validate
+gh-symphony workflow preview
 ```
 
 The interactive wizard will:
 
-1. Authenticate via `gh` CLI
+1. Authenticate via `GITHUB_GRAPHQL_TOKEN` or fall back to `gh` CLI
 2. Let you select a **GitHub Project** to bind
 3. Map project status columns to workflow phases (active / wait / terminal)
 4. Generate `WORKFLOW.md` and supporting files in the repository
 
+Token-only interactive setup is supported:
+
+```bash
+export GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token
+gh-symphony workflow init
+```
+
+Use `--dry-run` to preview the generated write plan first. The preview reports
+whether `WORKFLOW.md`, `.gh-symphony/context.yaml`,
+`.gh-symphony/reference-workflow.md`, and runtime skill files would be created,
+updated, or left unchanged, and then exits without modifying the repository.
+
 ### Customizing Agent Behavior
 
-`gh-symphony init` generates skill files under `.codex/skills/` (or `.claude/skills/` for Claude Code). These skills define how the AI agent handles commits, pushes, pulls, and project status transitions.
+`gh-symphony workflow init` generates skill files under `.codex/skills/` (or `.claude/skills/` for Claude Code). These skills define how the AI agent handles commits, pushes, pulls, and project status transitions.
 
 You can further customize the agent's behavior by editing `WORKFLOW.md` — this is the policy layer that controls what the agent does at each workflow phase.
 
@@ -104,25 +133,54 @@ gh-symphony project add
 
 The interactive wizard will:
 
-1. Authenticate via `gh` CLI
+1. Authenticate via `GITHUB_GRAPHQL_TOKEN` or fall back to `gh` CLI
 2. Let you select a **GitHub Project**
 3. Optionally limit processing to issues assigned to the authenticated user
 4. Optionally customize advanced settings for repository filtering and workspace root directory
 5. Write project configuration to `~/.gh-symphony/`
 
+Token-only non-interactive setup:
+
+```bash
+GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token \
+  gh-symphony workflow init --non-interactive --project PVT_xxx --output WORKFLOW.md
+
+GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token \
+  gh-symphony project add --non-interactive --project PVT_xxx --workspace-dir ~/.gh-symphony/workspaces
+```
+
+Token-only project registration is also supported:
+
+```bash
+export GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token
+gh-symphony project add
+```
+
 ### Project Management
 
 ```bash
+gh-symphony doctor                   # Validate local prerequisites, auth, config, WORKFLOW.md, and runtime command
+gh-symphony doctor --fix             # Apply safe fixes and guide/launch follow-up recovery commands
 gh-symphony project list             # List all configured projects
 gh-symphony project remove <id>      # Remove a project
+gh-symphony repo sync                # Add newly linked repositories from the GitHub Project
+gh-symphony repo sync --dry-run      # Preview linked repository drift
+gh-symphony repo sync --prune        # Remove local repositories no longer linked
 ```
 
+Use `gh-symphony repo sync` when the GitHub Project board has gained or lost
+linked repositories since the project was first added locally. Default sync is
+additive; `--prune` switches to strict alignment, and `--json` prints the added,
+removed, unchanged, and final repository sets.
+
 ## 4. Run the Orchestrator
 
 ### Foreground
 
 ```bash
 gh-symphony start
+gh-symphony start --once            # Run startup cleanup + one orchestration tick, then exit
+gh-symphony project start --once    # Same one-shot flow for an explicit project
 ```
 
 ### Background (daemon)
@@ -132,6 +190,8 @@ gh-symphony start --daemon          # Start in background
 gh-symphony stop                    # Stop the daemon
 ```
 
+Use `start --once` for the first real managed-project run or a CI smoke check. It reuses the configured GitHub Project binding and `WORKFLOW.md` and performs exactly one poll/reconcile/dispatch cycle instead of entering the long-running orchestration loop. `--daemon --once` is rejected because the modes conflict. If you add `--http`, the dashboard/API remains available after that one-shot tick completes, and the process stays up until you interrupt it with `Ctrl+C`.
+
 ### Monitor
 
 ```bash
@@ -154,17 +214,52 @@ gh-symphony recover                 # Recover stalled runs
 gh-symphony recover --dry-run       # Preview what would be recovered
 ```
 
+## Diagnostics
+
+`gh-symphony doctor` validates the most common first-run prerequisites in one pass. `gh-symphony doctor --fix` extends that flow with safe remediation and guided follow-up:
+
+- creates missing config/runtime/workspace directories
+- launches `gh auth login` or `gh auth refresh` when a TTY is available, otherwise prints the exact command to run
+- launches `gh-symphony init` when `WORKFLOW.md` is missing or invalid
+- launches `gh-symphony project add` when managed project setup or GitHub Project binding must be repaired
+- prints concrete runtime install guidance when the configured command is missing on `PATH`
+
+The diagnostic checks cover:
+
+- the active GitHub auth source (`GITHUB_GRAPHQL_TOKEN` first, otherwise `gh`) and required scopes
+- Node.js runtime version against the documented minimum (`v24+`) and the current `process.version`
+- Git installation availability on `PATH`, including `git --version` when available
+- GitHub authentication via `GITHUB_GRAPHQL_TOKEN` or `gh`, including required scopes
+- managed project selection plus GitHub Project binding resolution
+- config/runtime/workspace path writability
+- repository `WORKFLOW.md` presence and parse validity
+- runtime command availability on `PATH`
+
+Use JSON output for scripts and CI smoke checks. `--fix --json` includes a remediation section where each step is reported as `applied`, `skipped`, or `manual`.
+
+```bash
+gh-symphony doctor --json
+gh-symphony doctor --fix --json
+gh-symphony start --once
+```
+
+JSON output includes the resolved auth source as `env` or `gh`.
+
 ## Command Reference
 
 ```
 Setup:
-  init                Interactive repository setup wizard
+  workflow init       Interactive repository setup wizard
+  workflow validate   Parse and strictly validate WORKFLOW.md
+  workflow preview    Render the final worker prompt from a sample issue
+  doctor              Run diagnostics and optional first-run remediation
   config show         Show current configuration
   config set          Set a configuration value
   config edit         Open config in $EDITOR
 
 Orchestration:
   start               Start the orchestrator (foreground)
+  start --once        Run a single orchestration tick and exit
   start --daemon      Start the orchestrator (background)
   stop                Stop the background orchestrator
   status              Show orchestrator status
@@ -177,6 +272,7 @@ Project Management:
   project add          Add a new project (interactive wizard)
   project list         List all configured projects
   project remove       Remove a project
+  repo sync            Refresh repositories from the linked GitHub Project
 
 Global Options:
   --config <dir>      Config directory (default: ~/.gh-symphony)