Make the repository adoptable by anyone deploying Able

.claude/skills/deploy-able/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: deploy-able
+description: Drive an Able Desk deployment onto the user's own Cloudflare account, in order, stopping at every step only a human can complete. Use when the user wants to deploy Able, set it up for their business, stand up a support desk, resume a half-finished deployment, or check what is left before real customers can be served.
+---
+
+# Deploy Able for a business
+
+You are standing up **one single-tenant Able Desk deployment** in the user's Cloudflare account, on their domains, holding their data. There is no hosted Able service to sign into.
+
+[docs/deployment.md](../../../docs/deployment.md) is the authoritative runbook — read it before acting, and follow its steps in order. This skill is the driver: it tells you how to sequence the work, what you may do unattended, and where to stop.
+
+## Before you start
+
+1. Read `AGENTS.local.md` if it exists. It is the deployment's standing context — hostnames, which rails are on, where the deployment left off. If it does not exist, copy `AGENTS.local.example.md` to `AGENTS.local.md` and fill it in with the user as you go. Never commit it.
+2. Read `docs/adopt.md` for the tenant boundary. Nothing about this business goes into a tracked file.
+3. Establish where the deployment already is. A resumed deployment is the normal case — check what exists before creating anything: `npx wrangler whoami`, `npx wrangler d1 list`, `npx wrangler r2 bucket list`, `npx wrangler secret list`, and whether the Worker already serves `/healthz`.
+
+## Sequence
+
+Work `docs/deployment.md` §1 → §8 in order. Do not skip ahead: later steps fail confusingly when an earlier gate is incomplete, and several steps are irreversible in practice once customers are pointed at them.
+
+Announce which step you are on, what you are about to run, and what the user must do themselves. After each step, verify rather than assume — the runbook's §7 list is the acceptance criteria, not a formality.
+
+## You may do these unattended
+
+- `npm ci`, `npm run check`, `npm run build:assets`.
+- Read-only Wrangler and Cloudflare inspection to establish current state.
+- Apply committed D1 migrations (`npm run db:migrate:local`; `npm run db:migrate:remote` once the user confirms the target).
+- Generate values that should be random — for example a `CUSTOMER_CAPABILITY_SECRET` of at least 32 characters — and hand them to the user to set. Do not put a generated secret into a file, a commit, or your visible output beyond what the user needs to paste.
+- Draft workspace settings, knowledge articles, and email templates for the user's review.
+- Run the §7 validation checks and report results truthfully, including failures.
+
+## Stop and hand to the user
+
+These are not automatable, and attempting them produces a half-configured deployment that looks finished:
+
+- Proving domain ownership and binding the two custom hostnames.
+- Creating the Cloudflare Access application, its policy, and its group membership; enabling Managed OAuth for MCP clients.
+- Setting secrets. Ask the user to run each `npx wrangler secret put …` themselves. Never accept a secret value into the conversation, a file, or a command line.
+- Email Service onboarding, sender authentication, and confirming a real message landed in a real inbox. Provider acceptance is not delivery.
+- Creating the Turnstile widget, the Meta app and WABA, or any Shopify client.
+- **Enabling public intake and pointing real customers at the deployment.** This is the user's decision, made after §7 passes — never yours.
+
+## Report honestly
+
+A provisioned Worker is not an operational support desk. When you finish a session, state plainly which steps are complete, which are gated on the user, and which §7 checks have actually been run versus assumed. If a check failed, say so with its output. Update `AGENTS.local.md` with the new state so the next session resumes instead of restarting.

.gitignore

@@ -18,5 +18,13 @@ raw-imports/
 attachments/
 worker-configuration.d.ts
 wrangler.production.generated.json
-.claude/
-!.github/
+
+# Agent working state. Committed agent assets (.claude/skills, .claude/agents)
+# ship to adopters; local session state does not.
+.claude/worktrees/
+.claude/settings.local.json
+
+# Private deployment context. AGENTS.local.md is where a deployer's own
+# business may be named; the committed example template is not ignored.
+AGENTS.local.md
+*.local.md

AGENTS.local.example.md

@@ -0,0 +1,41 @@
+# Private deployment context (example)
+
+Copy this file to `AGENTS.local.md` and fill it in. `AGENTS.local.md` is git-ignored and rejected by `npm run scan:public`; it is the one place in your working copy where your business may be named.
+
+It is **context, not credentials.** Record what your agent needs to reason about your deployment. Never put a secret, token, capability, customer record, or raw export here — those belong in Wrangler secrets, Workers Builds variables, and `.dev.vars`.
+
+Delete the guidance lines and keep it short. A page an agent reads at the start of every session beats a runbook nobody maintains.
+
+---
+
+## Deployment
+
+- **Business:** <name customers see>
+- **Public portal hostname:** <help.example.com>
+- **Operator hostname:** <desk.example.com>
+- **Cloudflare account / Worker:** <which account; Worker name if it differs from the committed default>
+- **Where resource coordinates live:** <e.g. Workers Builds variables on the production trigger — name the location, not the values>
+- **Deployment trigger:** <Workers Builds on `main` / manual `npm run deploy:production` from a workstation>
+
+## Rails enabled
+
+- **Email:** <sender address, inbound routing status, setup test accepted?>
+- **Public intake:** <enabled / still gated>
+- **WhatsApp:** <off / pilot on test number / live number>
+- **Shopify order lookup:** <off / read-only / customer-account sign-in also on>
+- **Voice assistance:** <off / on>
+
+## Where we are
+
+- **Current goal:** <what this deployment is trying to reach next>
+- **Cutover state:** <what still runs on the system Able is replacing, and what has moved>
+- **Known gaps:** <capabilities customers need that Able does not have yet — these are your real blockers>
+- **Open decisions:** <things waiting on a human>
+
+## House rules for agents in this working copy
+
+- Tenant facts stay here, in the deployment platform, or in the running workspace settings — never in tracked files, tests, fixtures, issues, or commit messages.
+- Prefer level 1 (workspace settings) over level 2 (code) for anything customer-visible. See [docs/adopt.md](docs/adopt.md).
+- When a problem here is generic, fix it upstream with a neutral test rather than patching locally.
+- Run `npm run check` before any deploy; it includes the public-readiness scan.
+- <add your own: change windows, who approves a deploy, what must never be touched>

AGENTS.md

@@ -4,6 +4,15 @@
 
 Build a trustworthy, agent-first ERP for service businesses. Able Desk is the first application: a single-tenant Desk + CRM foundation on Cloudflare Workers where MCP is the normal operator interface, customers use accessible approved channels, and `/ops` is a small Cloudflare Access-protected recovery surface. Grow through deep business modules with small agent interfaces—not generic CRUD, a plug-in framework, or a universal object model.
 
+## Working context
+
+Two different jobs happen in this repository. Decide which one you are doing before you change anything.
+
+- **Upstream work** — improving Able itself. Everything you produce must be tenant-neutral: generic issues, neutral fixtures, no business named anywhere. This is the default when no private context is present.
+- **Deployment work** — configuring, deploying, or extending Able for one specific business. If `AGENTS.local.md` exists, read it first: it holds that deployment's standing context. Tenant facts belong there, in the deployment platform, or in runtime workspace settings — never in tracked files, tests, fixtures, commit messages, or issues.
+
+Prefer the lowest customization level that solves the problem: runtime workspace settings, then a module or adapter that respects the public seams, then core change. [docs/adopt.md](docs/adopt.md) defines the boundary and the levels; when deployment work uncovers a generic defect, fix it upstream with a neutral test instead of patching locally.
+
 ## Operating model
 
 Act as the lead orchestrator. Start from the user outcome, inspect relevant evidence, define the completion bar, and own integration and final verification. For sizeable work with genuinely independent streams, delegate bounded research, implementation, or review tasks with the context, constraints, success criteria, and expected return each delegate needs. Run safe independent reads in parallel. Work directly when the task is simple, sequential, or tightly coupled; do not delegate merely to duplicate work.
@@ -22,4 +31,4 @@ For an in-scope local change, implement it and run relevant non-destructive vali
 
 ## Canonical references
 
-Use [README.md](README.md) for the project and repository map, [docs/product-v1.md](docs/product-v1.md) for the binding Desk V1 contract, [docs/architecture.md](docs/architecture.md) and [docs/adr/](docs/adr/) for design boundaries, [docs/development.md](docs/development.md) for the upstream/proving-ground workflow, and [docs/roadmap.md](docs/roadmap.md) for direction. Put detailed path-specific rules beside the code or documentation they govern.
+Use [README.md](README.md) for the project and repository map, [docs/adopt.md](docs/adopt.md) for the adopter journey and tenant boundary, [docs/product-v1.md](docs/product-v1.md) for the binding Desk V1 contract, [docs/architecture.md](docs/architecture.md) and [docs/adr/](docs/adr/) for design boundaries, [docs/development.md](docs/development.md) for the upstream/proving-ground workflow, and [docs/roadmap.md](docs/roadmap.md) for direction. Put detailed path-specific rules beside the code or documentation they govern.

CHANGELOG.md

@@ -7,6 +7,14 @@ All notable changes to Able are documented in this file. The format follows [Kee
 ### Added
 
 - A public catalog-only UCP agent profile and Shopify Storefront Catalog MCP integration for bounded, live product search and detail.
+- Adopter guide at `docs/adopt.md`: prerequisites, fork-and-track-upstream setup, the tenant boundary, three customization levels, the human-only deployment gates, and the upgrade path.
+- `AGENTS.local.example.md`, a template for the git-ignored `AGENTS.local.md` where a deployer's own standing context lives. `npm run scan:public` now rejects any published `*.local.md` and requires both new documents.
+- Committed `/deploy-able` agent skill that drives `docs/deployment.md` in order and stops at every step only a human can complete.
+
+### Changed
+
+- `AGENTS.md` distinguishes upstream work from deployment work, points agents at `AGENTS.local.md` for private context, and states the customization-level preference.
+- `.gitignore` narrows the blanket `.claude/` rule to local session state so committed agent assets ship to adopters.
 
 ## [0.1.0] - 2026-08-01
 

README.md

@@ -9,7 +9,9 @@ Able Desk is the first application. It combines a support desk, customer directo
 
 > **Project status:** early V1. The architecture and core Desk flows are implemented and tested, but Able does not yet claim production readiness. A deployed Worker is not, by itself, an operational support desk.
 
-[Project site](https://codeyogi911.github.io/able-site/) · [V1 contract](docs/product-v1.md) · [Roadmap](docs/roadmap.md) · [Architecture overview](docs/architecture-overview.md) · [Architecture reference](docs/architecture.md)
+**Running it for your business?** Start with [docs/adopt.md](docs/adopt.md) — Able deploys into your own Cloudflare account, on your domains, holding your data. There is no hosted service.
+
+[Project site](https://codeyogi911.github.io/able-site/) · [Adopt Able](docs/adopt.md) · [V1 contract](docs/product-v1.md) · [Roadmap](docs/roadmap.md) · [Architecture overview](docs/architecture-overview.md) · [Architecture reference](docs/architecture.md)
 
 ![Able Desk architecture overview](docs/assets/architecture-overview.svg)
 
@@ -43,8 +45,9 @@ able/
 ├── apps/
 │   └── desk/          # Buildable Desk Worker, migrations, tests, assets, and configs
 ├── packages/          # Future reusable modules, extracted only behind proven interfaces
-├── docs/              # Product contract, architecture visuals, ADRs, deployment, and roadmap
+├── docs/              # Adopter guide, product contract, architecture, ADRs, deployment, roadmap
 ├── scripts/           # Repository-wide publication and history gates
+├── .claude/skills/    # Committed agent skills, including the guided deployment driver
 └── .github/           # CI, security scanning, and contributor templates
 ```