pushci 1.12.7 → 1.12.9

package/README.md

@@ -6,70 +6,22 @@
 [![Release](https://img.shields.io/github/v/release/finsavvyai/pushci-cli)](https://github.com/finsavvyai/pushci-cli/releases/latest)
 [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://pushci.dev/ai)
 
-**Local-first CI/CD validation for AI-generated code.**
+## AI agents write the code. PushCI proves it is safe to ship.
 
-> 35 languages. 49 frameworks. 22 deploy targets. Zero YAML.
-> One command to add a pre-push gate. Your existing CI can stay put.
+PushCI is an **independent delivery verification and promotion control plane for AI-written changes**. It issues signed proof tied to exact source, required checks, actor, immutable artifact, environment, database state, and policy before production.
 
-```bash
-npm install -g pushci   # one-time install
-pushci init             # AI detects your stack in 30 seconds
-git push                # tests run automatically
-```
-
-```
-$ pushci init
-  Detecting stack ........................ Node 20 + Vite + Vitest
-  Detecting deploy target ................ Cloudflare Workers (wrangler.toml)
-  Writing pushci.yml ..................... 14 lines
-  Installing pre-push hook ............... done
-
-$ git push
-  → running pushci run
-  ✓ lint                                                                3.2s
-  ✓ test                                                                8.4s
-  ✓ build                                                              12.1s
-  → 24 commits ahead of origin/main · all checks passed
-```
-
-See the current product surface at <a href="https://pushci.dev">pushci.dev</a>.
-
-## Why PushCI?
+The CLI is the human/native automation interface. MCP-compatible agents such as Claude Code, Cursor, Copilot, and Codex use the same governed primitives. PushCI can run work, but the independent receipt—not the executor's own green flag—is the admission record.
 
-Hosted CI minutes can get expensive when every AI-generated change queues a remote run. PushCI runs the first validation pass on your machine or runner pool before hosted CI starts.
-
-| | PushCI | GitHub Actions | GitLab CI | Jenkins |
-|--|---------|---------------|-----------|---------|
-| **Setup** | 30 seconds | 30+ minutes | 30+ minutes | Hours |
-| **Config** | Zero (AI) | 50+ lines YAML | 50+ lines YAML | Groovy DSL |
-| **Cost** | Your machine or runner pool | Hosted minutes | Hosted minutes | Server costs |
-| **Platforms** | GitHub + GitLab + BB | GitHub only | GitLab only | All |
-| **AI** | Auto-detects stack | None | None | None |
-
-## Quick Start
+PushCI runs beside existing GitHub Actions, GitLab CI, Buildkite, Jenkins, and provider delivery systems. Local, self-hosted, or customer-owned compute is the default; optional managed execution is capacity-capped, budgeted, and separately metered.
 
 ```bash
-# Install (pick one)
-npm install -g pushci                                          # npm (recommended)
-brew install finsavvyai/tap/pushci                             # Homebrew
-curl -fsSL https://pushci.dev/install.sh | sh                  # Script
-
-# Auto-detect your stack
+npm install -g pushci
 pushci init
-
-# Run CI locally
-pushci run
-
-# Something broken? Get actionable fixes
-pushci troubleshoot
-
-# Start the webhook server
-GITHUB_TOKEN=xxx pushci agent serve
+pushci verify --local
+pushci verify --publish  # authenticated, project-bound, server-signed receipt
 ```
 
-## AI Agent Integration (MCP)
-
-PushCI includes an MCP server for AI coding agents like **Claude Code**, **Cursor**, **Windsurf**, and **Cline**.
+Or expose the same delivery runtime to an AI agent:
 
 ```json
 {
@@ -82,427 +34,178 @@ PushCI includes an MCP server for AI coding agents like **Claude Code**, **Curso
 }
 ```
 
-**Available tools**: `pushci_init` (detect stack), `pushci_run` (run pipeline), `pushci_status` (check results), `pushci_doctor` (diagnose env), `pushci_secret_set` (store secrets).
-
-**Natural language**: `pushci ask "set up CI for this project"`
-
-## Supported
+## One independent proof across every executor
 
-**35 Languages**: Go, Node/TS, Python, Rust, Java, C#,
-Ruby, PHP, Swift, Dart, Elixir, Zig, Scala, Haskell,
-Kotlin, Lua, Perl, R, Julia, OCaml, Nim, Crystal, Bicep +more
-
-**39 Frameworks**: Next.js, Nuxt, SvelteKit, Django, FastAPI,
-Flask, Spring Boot, Rails, Laravel, Phoenix, Flutter +more
+```text
+Developer / coding agent
+          │
+          ├── existing CI or customer-owned runner
+          └── optional managed execution
+                      │
+                      ▼
+             PushCI verification gate
+                      ├── exact source / PR HEAD
+                      ├── required checks and actor
+                      ├── artifact digest
+                      ├── environment / database state
+                      └── policy and approval
+                                   │
+                                   ▼
+                         signed receipt → promotion
+```
 
-**22 Deploy Targets**: Cloudflare (Pages/Workers), AWS (ECS/Lambda/S3),
-GCP (Cloud Run/App Engine), Azure (App Service/Functions/Bicep),
-Vercel, Railway, Fly, Render, Netlify, Docker, K8s, SSH,
-Terraform, CloudFormation, Pulumi, Ansible
+The coding agent may be the author and any CI may be the executor. PushCI remains the independent judge of whether the exact change is eligible to move.
 
-## Messaging Channels
+## Why PushCI
 
-Control your CI/CD from WhatsApp, Slack, Discord, Telegram, or any webhook.
+Traditional CI assumes every change should begin by renting a clean remote machine. AI agents also tend to fall back to ad-hoc shell commands and provider-specific scripts when they need to deploy infrastructure. PushCI starts with a different model: **use the compute and delivery knowledge already available locally, expose it through one agent-friendly interface, and escalate to controlled infrastructure only when required.**
 
-```
-"run tests"        → PushCI runs your pipeline
-"deploy staging"   → Deploys to staging
-"status"           → Shows last run result
-"diagnose"         → AI root-cause analysis
+```text
+Existing repository / CI
+          │
+          ▼
+      PushCI init
+          │
+          ├── detect stack and workflow
+          ├── preserve/migrate existing CI
+          ▼
+Developer or AI agent
+          │
+          ▼
+   Local / self-hosted execution
+          │
+          ├── build
+          ├── test
+          ├── scan
+          └── migration analysis
+          │
+          ▼
+     immutable artifact
+          │
+          ▼
+   provision / preview / staging
+          │
+          ▼
+       verification
+          │
+          ▼
+      safe promotion
 ```
 
-Connect from the dashboard at **app.pushci.dev/channels**, or via API:
+PushCI is deliberately **local-first, not local-only**. Fast validation can run on the developer machine; teams can use self-hosted runner pools and optional managed execution. Existing GitHub Actions, GitLab CI, Jenkins, Buildkite, and other delivery systems can remain in place while workloads migrate incrementally.
 
-```bash
-curl -X POST https://api.pushci.dev/api/channels/connect \
-  -H "Authorization: Bearer $TOKEN" \
-  -d '{"channelType":"slack","credentials":{"accessToken":"xoxb-...","teamId":"T123"}}'
-```
+## Core value
 
-Supported platforms:
+### Agent-native delivery
 
-| Platform | Webhook | Response Limit |
-|----------|---------|----------------|
-| WhatsApp | Meta Business API | 4,000 chars |
-| Slack | Events API | 39,000 chars |
-| Discord | Interactions | 2,000 chars |
-| Telegram | Bot API | 4,000 chars |
-| Custom | Webhook | 40,000 chars |
+The CLI and MCP server expose the delivery lifecycle as callable capabilities. An agent can inspect a repository, initialize/migrate its pipeline, run tests, diagnose failures, manage secrets, provision supported infrastructure, create preview environments, deploy, and request verification without learning each provider's bespoke operational interface.
 
-## Commands
+This is the strategic agent loop:
 
-```
-pushci init         Detect stack and generate pushci.yml
-pushci run          Execute pipeline checks
-pushci deploy       Deploy to target environment
-pushci diagnose     AI-diagnose failed runs
-pushci status       Show last run results
-pushci secrets      Manage encrypted secrets
-pushci heal         AI self-heal broken pipeline
-pushci ask          Natural language CI commands
-pushci generate     AI-generate pushci.yml
-pushci migrate      Convert GitHub Actions workflow
-pushci mcp          Start MCP server for AI agents
-pushci agent        Run AI workflows or the webhook server
-pushci runner       Manage self-hosted execution capacity
-pushci index        Build dependency graph for blast radius
-pushci skill        Install/list/remove marketplace skills
-pushci login        Authenticate with PushCI (Pro)
-pushci logout       Remove saved credentials
-pushci doctor       Check environment health
-pushci troubleshoot Diagnose issues with actionable fixes
-pushci trace        View Perfetto performance traces
-pushci release      Build & publish release locally ($0)
-pushci promote      Register with AI registries
-pushci voice        TTS narration for runs (curb / office / deadpan-tech)
-pushci uninstall --yes  Remove hooks, config, and .pushci after confirmation
-pushci version      Print version
+```text
+agent writes code
+    ↓
+pushci build / run
+    ↓
+failure → structured diagnosis → repair
+    ↓
+pushci provision / preview
+    ↓
+integration verification
+    ↓
+pushci deploy / promote
+    ↓
+receipt + audit trail
 ```
 
-See [docs/CLI.md](docs/CLI.md) for the full CLI reference with flags, examples, and plan requirements.
+The long-term goal is **bounded autonomy**: agents can move software forward quickly, while PushCI supplies policy, credentials boundaries, environment isolation, artifact lineage, and verification evidence.
 
-## Voice
+### Use the compute you already own
 
-PushCI narrates your pipeline. Pick a persona, run your pipeline, hear it. Phrases are pre-canned by default; with an AI key you get fresh in-character lines per run.
+Keep install, lint, unit tests, builds, scans, and other cache-friendly work local when policy allows it. Remote infrastructure is reserved for stages that actually require cloud bindings, shared services, controlled builders, or realistic environments.
 
-```bash
-pushci voice list                              # show built-in personas
-pushci voice say "deploying" --persona curb-style
-pushci voice test --persona office-style       # demo all 6 lifecycle events
-pushci voice joke --diff main                  # AI riffs on the diff vs main
-pushci run --voice                             # auto-narrate pipeline events
-```
+### Migrate without a platform rewrite
 
-Built-in personas:
+`pushci init` detects stack and existing CI intent. The target experience is side-by-side adoption: run PushCI locally, prove the feedback/cost benefit, then migrate selected expensive stages when the team is ready. This also gives agents a normalized interface over legacy delivery systems rather than requiring them to rewrite everything first.
 
-| Persona | Style |
-|---|---|
-| `curb-style` | Petty frustration, awkward incredulity |
-| `office-style` | Oblivious enthusiasm, motivational confusion |
-| `deadpan-tech` | Sysadmin superiority, dark contempt |
-| `deadpan-narrator` | Neutral, no character |
+### Build once, promote the verified artifact
 
-Defaults are zero-config: macOS `say` backend, no API keys, no network. Add `--ai` (or `PUSHCI_VOICE_AI=1` for `pushci run`) to switch on AI commentary via the configured provider paths (`ANTHROPIC_API_KEY` / `GROQ_API_KEY` / `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / local llamafile).
+Where the deployment target supports immutable artifacts, PushCI's direction is build-once/promote-everywhere. Preview, staging, and production should refer to the same artifact digest rather than silently rebuilding different binaries at every step.
 
-Safety: every utterance passes through a redactor (JWTs, AWS ARNs, account IDs, API keys, IPs, internal hostnames, emails are masked) and AI output runs through a content filter (rejects profanity + prompt-injection echo). Mute everything with `PUSHCI_VOICE_OFF=1`.
+### Verify realistic environments
 
-Bring your own personas via `~/.pushci/voices.yml` — user entries appear in `pushci voice list` alongside the built-ins and override on name collision:
+PushCI includes preview-environment lifecycle capabilities. Preview and staging can become structured verification evidence including provider/target identity, database isolation, migration state, configuration/binding fingerprints, health checks, and the exact artifact deployed.
 
-```yaml
-personas:
-  - name: pirate-style
-    voice: Daniel        # macOS voice; run `say -v ?` to enumerate
-    description: Pirate-themed deploy commentary
-    phrases:
-      start: ["Aye, hoist the colors. Deploying."]
-      pass:  ["Ye scurvy tests passed."]
-      fail:  ["Avast, the build hath sunk."]
-```
+### Govern human and AI-generated changes
 
-## Secrets
-
-PushCI resolves secret references inline in `pushci.yml` env blocks.
-Three schemes are supported today; PushCI never writes a plaintext
-secret to disk it didn't already encrypt.
-
-| Scheme | Backed by | Best for |
-|---|---|---|
-| `keychain://service[#account]` | macOS Keychain / Windows Credential Manager / Linux Secret Service, with AES-encrypted fallback at `~/.pushci/keychain.enc` for headless CI | Local dev, individual machines |
-| `vault://path#field` | HashiCorp Vault AppRole (`VAULT_ADDR` + `VAULT_ROLE_ID` + `VAULT_SECRET_ID`) | Teams, audited environments |
-| `pushci secrets set KEY VAL` | Per-project AES file at `.pushci/secrets.enc`, machine-bound | Quick one-offs, throwaway scripts |
-
-```yaml
-# pushci.yml
-stages:
-  - name: publish
-    env:
-      NPM_TOKEN: keychain://npm-publish-token
-      DEPLOY_KEY: keychain://deploy-bot#prod
-      DB_PASSWORD: vault://secret/data/prod/db#password
-    checks:
-      - name: publish
-        run: npm publish
-```
+Humans and agents use the same delivery primitives but can receive different policy. PushCI can record actor/provenance when available, apply stricter requirements to autonomous changes, and preserve an audit trail of what an agent actually built, provisioned, changed, and deployed.
 
-**Managing keychain entries from the CLI:**
+## Quick start
 
 ```bash
-pushci secrets keychain set npm-publish-token npm_xxxxxxxxxxxx
-pushci secrets keychain set deploy-bot#prod  s3cr3t
-pushci secrets keychain get npm-publish-token
-pushci secrets keychain list      # fallback-file entries only
-pushci secrets keychain rm  npm-publish-token
+npm install -g pushci
+pushci init
+pushci verify
 ```
 
-On macOS the storage layout matches the `security` CLI verbatim, so the
-common `.zshrc` helper functions work side-by-side:
+Other install options:
 
 ```bash
-secret()     { security find-generic-password -a "$USER" -s "$1" -w 2>/dev/null; }
-secret-set() { security add-generic-password    -a "$USER" -s "$1" -w "$2" -U; }
+brew install finsavvyai/tap/pushci
+curl -fsSL https://pushci.dev/install.sh | sh
 ```
 
-Entries written by `secret-set` are readable by `pushci secrets keychain
-get`, and vice versa — no `go-keyring-base64:` prefix gymnastics.
-
-**Headless Linux CI:** when D-Bus and Secret Service aren't running,
-PushCI falls back transparently to an AES-encrypted file at
-`~/.pushci/keychain.enc` with a machine-bound key. A one-time stderr
-warning fires the first time a fallback read or write happens, so the
-behavior is never silent. Override account default with the `#account`
-suffix; the current OS user is used when omitted.
-
-## Configuration
-
-`pushci.yml` is optional — `pushci init` generates one that works, and
-zero-config mode auto-detects your stack. When you want more control,
-PushCI supports three authoring styles. Full reference is at
-[pushci.dev/docs/pushci-yaml](https://pushci.dev/docs/pushci-yaml).
-
-### Simple example
-
-Zero-config Node.js app with linear stages, single-target deploy on
-`main`, and Slack notifications. Drop this into your repo as
-`pushci.yml` and run `pushci run`.
-
-```yaml
-on: [push, pull_request]
-
-stages:
-  - name: install
-    checks:
-      - name: deps
-        run: pnpm install --frozen-lockfile
-
-  - name: lint
-    depends_on: [install]
-    checks:
-      - name: eslint
-        run: pnpm lint
-
-  - name: test
-    depends_on: [install]
-    checks:
-      - name: vitest
-        run: pnpm test
-
-  - name: build
-    depends_on: [install, lint, test]
-    checks:
-      - name: next-build
-        run: pnpm build
-
-deploy:
-  trigger: push
-  only_on: [main]
-  run: npx wrangler pages deploy dist --project-name=my-app
-
-notify:
-  slack: "${{ secrets.SLACK_WEBHOOK }}"
-```
+Useful commands:
 
-### Complex example — every feature
-
-Parallel stages, cross-stage DAG, conditional checks, retries,
-timeouts, Docker-isolated steps, multi-environment staged deploy with
-an approval gate on production, and stage-scoped secrets.
-
-```yaml
-on: [push, pull_request, workflow_dispatch]
-
-stages:
-  - name: install
-    checks:
-      - name: pnpm-install
-        run: pnpm install --frozen-lockfile
-        retry: 2
-        timeout: 3m
-
-  - name: quality
-    depends_on: [install]
-    parallel: true            # every check runs concurrently
-    env:
-      NODE_ENV: test
-    checks:
-      - name: typecheck
-        run: pnpm tsc --noEmit
-      - name: lint
-        run: pnpm lint
-      - name: format
-        run: pnpm prettier --check .
-      - name: audit
-        run: pnpm audit --audit-level=high
-        on_fail: warn         # log but don't fail the stage
-
-  - name: test
-    depends_on: [install]
-    parallel: true
-    env:
-      DATABASE_URL: postgres://test:test@localhost:5432/test
-    checks:
-      - name: unit
-        run: pnpm test:unit --coverage
-      - name: integration
-        run: pnpm test:integration
-        retry: 1
-        timeout: 5m
-      - name: e2e
-        if: branch == 'main' || branch =~ '^release/'
-        run: pnpm test:e2e
-        docker: mcr.microsoft.com/playwright:v1.49.0-focal
-        timeout: 10m
-
-  - name: security
-    depends_on: [install]
-    checks:
-      - name: secret-scan
-        run: npx gitleaks detect --no-git
-      - name: sast
-        run: pushci scan --engine claude --fail-on high
-
-  - name: build
-    depends_on: [quality, test, security]
-    checks:
-      - name: next-build
-        run: pnpm build
-      - name: bundle-size
-        run: npx size-limit
-        line-limit: 10
-
-deploy:
-  trigger: push
-  environments:
-    - name: staging
-      only_on: [develop]
-      run: npx wrangler pages deploy dist --project-name=app-staging
-      env:
-        CF_API_TOKEN: "${{ secrets.CF_API_TOKEN_STAGING }}"
-    - name: production
-      only_on: [main]
-      approve: true           # requires interactive approval
-      run: npx wrangler pages deploy dist --project-name=app-prod
-      env:
-        CF_API_TOKEN: "${{ secrets.CF_API_TOKEN_PROD }}"
-
-notify:
-  slack: "${{ secrets.SLACK_WEBHOOK }}"
-  discord: "${{ secrets.DISCORD_WEBHOOK }}"
-  email: oncall@example.com
+```text
+pushci init          detect the stack and configure/migrate validation
+pushci verify        verify the current change and produce evidence
+pushci run           execute the pipeline directly
+pushci preview       manage realistic preview environments
+pushci migrate       migrate an existing GitHub Actions workflow
+pushci deploy        validate and execute deployments
+pushci troubleshoot  diagnose failures with actionable fixes
+pushci index         build the dependency graph / blast-radius model
+pushci mcp           expose PushCI delivery capabilities to AI coding agents
+pushci mcp configure hermes  install a governed Hermes delivery operator
+pushci agent         run PushCI agent workflows
+pushci runner        manage execution capacity
 ```
 
-Immutable deploy targets can also enforce `staging → production` or the
-sensitive `candidate → staging → candidate → sandbox → candidate → production`
-path. See [Release Flow Policies](docs/RELEASE_FLOWS.md).
-
-### GitHub Actions parity — no rewrite needed
+## AI-agent integration
 
-PushCI v1.3.1+ runs your existing `.github/workflows/*.yml` files
-end-to-end via the embedded [nektos/act](https://github.com/nektos/act)
-runtime. `actions/checkout@v4`, matrix builds, service containers,
-composite actions, secret masking, `needs.*.outputs.*` — all work.
-Just drop in a workflow and run:
-
-```bash
-pushci actions run                 # runs all .github/workflows/*.yml
-pushci actions run --job test      # run one job
-pushci actions run --dry-run       # validate without containers
-pushci actions doctor              # check act + docker + workflow status
-```
+PushCI includes an MCP server for coding agents such as Claude Code, Cursor, Windsurf, Cline, and other MCP-compatible clients.
 
-A real complex workflow that runs unchanged:
-
-```yaml
-name: CI
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        node: [20, 22]
-    services:
-      postgres:
-        image: postgres:16
-        env:
-          POSTGRES_PASSWORD: test
-        ports: ['5432:5432']
-        options: >-
-          --health-cmd pg_isready --health-interval 10s
-          --health-timeout 5s --health-retries 5
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node }}
-      - run: npm ci
-      - run: npm test
-        env:
-          DATABASE_URL: postgres://postgres:test@localhost:5432/postgres
-      - id: coverage
-        run: echo "pct=$(npm test --silent)" >> $GITHUB_OUTPUT
-    outputs:
-      coverage: ${{ steps.coverage.outputs.pct }}
-
-  deploy:
-    needs: test
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - uses: actions/checkout@v4
-      - name: Deploy
-        run: echo "coverage was ${{ needs.test.outputs.coverage }}"
-        env:
-          CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
+```json
+{
+  "mcpServers": {
+    "pushci": {
+      "command": "pushci",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
-Or just run `pushci init` — PushCI figures everything out automatically.
-
-## Git Hook
-
-`pushci init` installs a pre-push hook that runs checks before every push.
-The hook is designed to never block your workflow:
-
-- **Skip once**: `git push --no-verify`
-- **Disable permanently**: `export PUSHCI_SKIP_HOOK=1`
-- **Auto-skips** if the pushci binary is unavailable (no download hang)
+Available MCP capabilities include stack detection, pipeline initialization, pipeline execution, status, environment diagnosis, secret management, security scanning, migration recommendations, healing/diagnosis, and agent workflows. The product direction is to expose provisioning, preview, verification, and promotion through the same governed agent interface wherever the underlying PushCI capability is already available and safe to expose.
 
-## Pricing
+## Verification model
 
-| Free | Pro $9/mo | Team $29/seat/mo | Enterprise |
-|------|-----------|-------------------|------------|
-| Unlimited local runs | Unlimited repos | Everything in Pro | Everything in Team |
-| AI stack detection | AI diagnosis (100/mo) | 2000 cloud minutes | Unlimited cloud minutes |
-| 2 deploy targets | 22 deploy targets | SSO / SAML | SCIM + 7-year audit |
-| Community support | Dashboard + analytics | Audit logs + governance | Dedicated tenant option |
+The core product primitive is a software-change **verification**. A verification binds evidence not only to code, but to the delivery path an agent or developer executed: exact repository/commit and dirty-tree state, actor, checks, artifact, environment, migration state, policy, savings, and results.
 
-## Links
+Receipts have deterministic local identities and tamper-checked history. `pushci verify --publish` sends a completed receipt to the authenticated project, where the control plane independently recomputes its evidence hash, stores an audited ledger row, and returns a project-bound ECDSA P-256 attestation. In the immutable image-promotion path, artifact passports embed that receipt and production requires the exact published attestation. GitHub repositories can also receive one `PushCI / Verification` Check Run bound to the live PR HEAD; a new HEAD immediately makes the prior receipt ineligible. Locally asserted agent metadata remains distinguishable from provider-verified provenance.
 
-- **Website**: https://pushci.dev
-- **AI Agents**: https://pushci.dev/ai
-- **Cost Calculator**: https://pushci.dev/tools/cost-calculator
-- **Compare**: [vs GitHub Actions](https://pushci.dev/vs/github-actions) | [vs GitLab CI](https://pushci.dev/vs/gitlab-ci) | [vs CircleCI](https://pushci.dev/vs/circleci) | [vs Jenkins](https://pushci.dev/vs/jenkins)
+## Documentation
 
-## Contributing
-
-We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and contribution guidelines.
-
-**Good first issues:**
-- Add a framework detector (`internal/detect/`)
-- Add a deploy target (`internal/deploy/`)
-- Improve CLI error messages
-- Add tests
-
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
-
-## Security
-
-Found a vulnerability? See [SECURITY.md](SECURITY.md) for our disclosure policy.
+- [CLI reference](docs/CLI.md)
+- [Verification evidence](docs/VERIFICATION_EVIDENCE.md)
+- [Verification marketing claim matrix](docs/VERIFICATION_MARKETING_CLAIM_MATRIX.md)
+- [AI / MCP integration](https://pushci.dev/ai)
+- [pushci.yml guide](https://pushci.dev/docs/pushci-yaml)
+- [Build roadmap](ROADMAP.md)
+- [GitHub App and verification implementation plan](.planning/github-app-verification-plan.md)
+- [Product refinement opportunities](.planning/product-refinement-opportunities.md)
 
 ## License
 
-[BSL 1.1](LICENSE) (Business Source License). Free to use for any purpose except
-offering a competing hosted CI/CD service. Converts to MIT on 2029-04-06.
-
-PushCI is a trademark of FinsavvyAI. See [LICENSE](LICENSE) for full terms.
+PushCI is licensed under BUSL-1.1. See [LICENSE](LICENSE).