# deploy-version: 0.1.953
# free-claim: /isco-1212/
# free-claim-url: /isco-1212/
# free-claim-agent: /isco-1212/agent.json
# free-claim-ui: /isco-1212/
# free-claim-docs: /docs/free-path.md
# free-path-docs: /docs/free-path.md
# free-path-api: /api/freepath
# free-path-api-alias: /api/free-path
# itonami.cloud — free path (no Stripe)

Machine-checkable free path for operators and agents. Paid path is separate
(`/docs/stripe-billing-setup.md`).

Agent discovery: [openapi-free-path.json](/openapi-free-path.json) · [ai-plugin.json](/.well-known/ai-plugin.json)

## One-shot health

```bash
curl -sS -A 'my-agent/1.0' https://itonami.cloud/api/health | jq .
curl -sS -A 'my-agent/1.0' https://itonami.cloud/api/freepath | jq .
curl -sS -A 'my-agent/1.0' https://itonami.cloud/api/status | jq '.scores,.freePath,.nextOwnerActions'
curl -sS -A 'my-agent/1.0' https://itonami.cloud/api/metrics | jq '.freePath'
```

Use a non-empty **User-Agent**. Default `Python-urllib/*` may get Cloudflare **403 / 1010**.


## freeClaim + freePath densify (agents)

Every free-path JSON surface densifies machine-readable claim pointers:

| Field | Value |
|---|---|
| `freeClaim` | `/isco-1212/` |
| `freeClaimUrl` | `/isco-1212/` (dual of freeClaim) |
| `freeClaimAgent` | `/isco-1212/agent.json` |
| `freeClaimUi` | `/isco-1212/` |
| `freeClaimDocs` | `/docs/free-path.md` (this file) |
| `freePathDocs` | `/docs/free-path.md` (dual of freeClaimDocs on freePath nests) |

Nested maps:

- **`freePath`** object on digests/catalogs: `{ ok, freeClaim, freeClaimAgent, freeClaimUi, freeClaimDocs, freePathDocs, docs, …counts }` — `docs` duals `freePathDocs`
- **`freePathDetail`** when `freePath` is a boolean (e.g. `/api/freepath`, `/api/maturity`): same claim fields + counters + `docs` dual
- **`links.freeClaim*`** dual keys on discovery maps (includes `freeClaimUrl` + `freePathDocs`)
- **`nextOwnerActions[]`**: freeClaim tetrad + freePathDocs on every owner action
- Headers: `x-itonami-free-claim`, `-url`, `-agent`, `-ui`, `-docs`, plus dual `x-itonami-free-path-docs`
- OpenAPI: `FreeClaimFields` · `FreePathNest` · `FreeClaimDiscovery` · `NextOwnerAction` in `/openapi-free-path.json`

```bash
curl -sS -A 'my-agent/1.0' https://itonami.cloud/api/health | jq '.freeClaimDocs,.freePath.freeClaimDocs,.links.freeClaimDocs'
curl -sS -A 'my-agent/1.0' https://itonami.cloud/api/open-business/6399 | jq '.freePath'
curl -sS -I -A 'my-agent/1.0' https://itonami.cloud/api/freepath | grep -i free-claim
```


## Surfaces that work without Stripe

| Surface | URL |
|---|---|
| Live free-path health | `/api/health` |
| Free-path badge (SVG) | `/api/badge` |
| Maturity checklist | `/api/status` (productSurface 6340/6340 free-path target) |
| Compact maturity | `/api/maturity` (digest; full checklist stays on `/api/status`) |
| Licenses catalog | `/licenses.json` (public kyoninka procedures) |
| Licenses UI | `/licenses/` (human-readable procedures) |
| BMC metrics + freePath | `/api/metrics` |
| Jobs meta-search | `/api/jobs?q=&location=&remote=1&limit=` |
| Jobs remote filter | `/api/jobs?remote=1` |
| Jobs location filter | `/api/jobs?location=USA` |
| Open business registry | `/api/open-business?q=&limit=` |
| Open business dry-run | `POST /api/open-business/{isic}/{intakes\|recommendations\|approvals}` |
| Marketplace search | `/api/marketplace?q=&limit=` (e.g. `q=talent`, `q=6399`) |
| Market entry | `/api/market-entry?q=&country=JPN` |
| Billing gate (booleans only) | `/api/billing/status` |
| Free tenant claim (passkey) | `/isco-1212/` |
| Agent runs (7d dry-run log) | `/api/agent-runs` |
| Free-path digest | `/api/freepath` (alias `/api/free-path`) |
| Flagships | 6399 / 6310 / 7810 github.io demos |
| Wedge Pages (20) | [wedge-pages.md](./wedge-pages.md) — insurance/health/IT etc. |
| Go-live runbook | `/docs/go-live.md` (free claim → paid path) |

## Local smoke

```bash
npm run free-path-smoke   # or: kbb --backend sci scripts/free_path_smoke.cljk
```

Expect all smoke lines OK (productSurface 6340/6340 free path; paid stripe checks stay owner-only).

## Claim a free tenant

1. Open https://itonami.cloud/isco-1212/ (unique org/repo prefilled)
2. **Sign up with Passkey (claim free tenant)** — no Stripe
3. Re-check `/api/fleet/metrics` → `selfRegisteredOwners` / `externalTotal`

Dogfood seeds already present (free tenants — not paid):

- `ops-maturity-seed/hr-practice` (ISIC 8299)
- `ops-placement-seed/agency` (ISIC 7810)
- `ops-jobs-seed/meta-search` (ISIC 6399)
- `ops-talent-seed/practice` (ISIC 6310)

## What free path does **not** clear

- `stripe-configured` / `paid-tenant` on `/api/status`
- `hyp/itonami-smb-pay` (needs ≥1 external **paid** org)

Owner: `/docs/stripe-billing-setup.md` (`sk_test_` is enough to clear `stripe-configured`).
## Keep productSurface warm

If dry-run / agent-runs probes go stale, free-path status can flap:

```bash
kbb --backend sci scripts/warm-flagship-dry-runs.cljk
```

## Owner next action (machine-readable)

```bash
curl -sS -A 'agent/1' https://itonami.cloud/api/freepath | jq '.bottleneck,.nextOwnerActions,.stripe'
```

When Stripe is configured and `externalPaid=0`, `nextOwnerActions[0].id` is `first-paid-checkout`.


## Dry-run methods

- Dry-run paths are **POST-only**: `/api/open-business/{isic}/{intakes|recommendations|approvals}`
- `GET` on those paths returns **405 JSON** (`error: method-not-allowed`) with `howTo.dryRun` — not HTML/502

## Fleet index + catalog nextOwner

- Fleet discovery (no counters): `GET /api/fleet` → links to `/api/fleet/metrics` and `nextOwnerActions`
- Catalog surfaces also expose the same paid gate when free path is live:
  - `GET /api/jobs` · `GET /api/marketplace` · `GET /api/market-entry` · `GET /api/open-business` · `GET /api/agent-runs`
- Each returns `bottleneck` + `nextOwnerActions[0].id === "first-paid-checkout"` until a real Stripe Checkout completes.
- Discovery URLs live under `links` (and the legacy alias `maturityLinks`) — e.g. `links.fleet` → `/api/fleet`
- Status map: `GET /api/status` → `freePath.checkoutPreflight` + `freePath.fleetIndex` + `links.fleetIndex`

```bash
curl -sS -A 'agent/1' https://itonami.cloud/api/fleet | jq '.links,.nextOwnerActions'
curl -sS -A 'agent/1' 'https://itonami.cloud/api/jobs?limit=1' | jq '.bottleneck,.nextOwnerActions'
```

## POST-only operator paths

- `GET /api/stripe/webhook`, `GET /api/webauthn/*`, `GET /api/nudge/scan` return **405 JSON** with `howTo.post` (not SPA 502)
- Public free-path digests remain GET: `/api/health`, `/api/freepath`, `/api/billing/status`

## Tenant API navigation

- `GET /api/org` — pattern for `/api/{org}/{repo}/metrics`
- `GET /api/{org}` — org-level discovery (no public tenant list)
- `GET /api/{org}/{repo}` — tenant endpoint map (metrics/register/state)
- `GET /api/{org}/{repo}/metrics` — counters + nextOwnerActions
- Unknown single-segment paths under `/api/__*` stay fail-closed (502 html-leak guard)

## Machine-readable claim gate

- `GET /isco-1212/agent.json` — free claim + first-paid-checkout instructions for agents (no HTML scrape)

## Catalog deploy version

- `GET /api/jobs`, `/api/marketplace`, `/api/open-business`, `/api/market-entry` include body `version` and `x-itonami-version` matching `/health.json`.
- Live health links: `freeClaimAgent` → `/isco-1212/agent.json`.
- `GET /api/open-business/{isic}` and dry-run POST/GET-405 also publish `version` + `x-itonami-version`.
- POST-only surfaces (`/api/stripe/webhook`, `/api/webauthn/*`, `/api/nudge/scan`): GET → 405 JSON with deploy `version`.
- `GET /api/billing/status` and `GET /api/{org}/{repo}/metrics` publish deploy `version` + `x-itonami-version`.
- `GET /api/status` body includes deploy `version`; `GET /api/{org}/{repo}/state` publishes version + free-path headers.
- `GET /isco-1212/agent.json` publishes `x-itonami-version` (function wrapper over static gate JSON).
- Unknown `/api/*` paths return JSON 502 `api-route-html-leak` with deploy `version` + freeClaimAgent pointer (no SPA HTML leak).
- Monitors can HEAD `/api/health`, `/api/badge`, `/api/freepath` for `x-itonami-free-claim-agent: /isco-1212/agent.json` without body parse.
- Free-path digests share `freeClaimMonitorHeaders` (`x-itonami-free-claim` + `x-itonami-free-claim-agent`) so HEAD probes find the claim gate without body parse.
- Tenant state/metrics/org indexes + open-business item/dry-run + POST-only 405/502 guards advertise freeClaimAgent headers for HEAD probes.
- Static discovery surfaces (OpenAPI, licenses, catalogs, docs) advertise freeClaimAgent headers; OpenAPI/licenses also expose deploy `x-itonami-version` via Pages Functions.
- `marketplace.json`, `open-business.json`, and `/.well-known/ai-plugin.json` publish deploy version headers (Pages Functions) like OpenAPI/licenses.
- `GET /health.json` and `GET /llms.txt` publish deploy version headers (Pages Functions) for agent/monitor probes.
- `robots.txt`, `sitemap.xml`, `security.txt`, and free-path docs publish deploy version headers for agent probes.