{
  "service": "Nomos Cloud",
  "by": "Captain App",
  "url": "https://nomos.captainapp.co.uk",
  "description": "Local-first domains on edge holons. Ledgers are git (custody, not truth); holons verify everything they run.",
  "start": {
    "what": "Author a domain in TypeScript (aggregates + directives on @githolon/dsl), compile it to content-addressed law, run it on an edge holon here. Clients work OFFLINE against the same byte-identical wasm runtime and sync through git; the edge re-verifies every write (admission), trusts nothing.",
    "quickstart": [
      "npm create githolon@latest my-app && cd my-app && npm install",
      "npx githolon compile          # your law + manifests + deploy body + a typed TS client -> build/",
      "npx githolon proof            # a proof GENERATED from your own law - no test rewriting",
      "npx githolon login --agent    # a VERIFIED identity in one command - no browser, no signup form",
      "npx githolon ws create <ws>   # birth a workspace; its one-time secret is saved to ~/.holon for you",
      "npx githolon deploy <ws>      # install your law (Active + content hash back)",
      "npm run e2e                # the full loop, live: offline write -> sync -> edge admission -> cloud query"
    ],
    "localFirst": [
      "npx githolon ledger init holon   # mint a REAL holon locally: genesis + your law, under YOUR identity, verified by the SAME wasm gate this cloud runs",
      "cd holon && npx githolon git remote <ws> && git push nomos main   # the upload birth: the cloud replay-verifies your chain and re-derives your exact local verdict"
    ],
    "authoring": {
      "model": "You write exactly TWO things: aggregates (typed fields, each tagged with a MERGE DRIVER) and directives (a zod payload -> a PURE plan emitting ops). Never apply/fold/merge code - the kernel owns folding. Declared reads (query/count/derived) are auto-discovered from your module's exports.",
      "example": [
        "import { z } from \"zod\";",
        "import { aggregate, t, Lww, AddWins, MapOf, directive, create, instance, set, addToSet, setEntry, query, count } from \"@githolon/dsl\";",
        "",
        "export const Book = aggregate(\"Book\", {",
        "  title: t.string().merge(Lww),             // last write wins",
        "  shelf: t.string().merge(Lww),",
        "  tags:  t.set(t.string()).merge(AddWins),  // concurrent adds ALL survive the merge",
        "  notes: t.map(t.string()).merge(MapOf(Lww)), // per-key LWW",
        "});",
        "",
        "export const addBook = directive(\"addBook\").creates(Book)   // the id is MINTED - payloads never carry one",
        "  .payload(z.object({ title: z.string(), shelf: z.string(), addedAt: z.string() })) // timestamps ride IN the payload",
        "  .plan((p) => { const b = create(Book); b.set(\"title\", p.title); b.set(\"shelf\", p.shelf); return []; });",
        "",
        "export const tagBook = directive(\"tagBook\").mutates(Book)",
        "  .payload(z.object({ bookId: z.string(), tags: z.array(z.string()) }))",
        "  .plan((p) => [addToSet(instance(Book, p.bookId), \"tags\", p.tags)]); // addToSet, NOT set - see planOps",
        "",
        "export const booksByShelf = query(\"booksByShelf\").key(\"shelf\").returns(Book);",
        "export const booksPerShelf = count(\"booksPerShelf\").of(Book).by(\"shelf\");"
      ],
      "planOps": "Plan ops: set (scalars/refs) | addToSet (the ONLY additive write to an AddWins set - set() on a set field is REFUSED at type level and runtime) | setEntry (map key) | strike. Drivers: Lww | AddWins | MapOf(Lww) | Conflict (fail-closed default). Full reference = hover any @githolon/dsl export in your editor.",
      "rules": "Determinism or death: plans are PURE fns of (payload) - timestamps ride IN the payload as ISO strings; ids are MINTED by create()."
    },
    "client": {
      "surface": "@githolon/client ships full TypeScript types - hover connect()/sync()/deadLetters() in your editor for the semantics (e.g. sync() returns admission: null when there was nothing to push - normal, not an error). `githolon compile` emits build/<name>.client.ts (typed methods per directive, accessors per query/count, the law hash baked in) and build/<name>.summary.txt describing exactly what you built.",
      "concurrency": "The scaffold's test/e2e.mts DEMONSTRATES the whole loop live - including two clients with different clientIds tagging the same entry offline and the AddWins union keeping every add. Run npm run e2e; read that file as the tutorial."
    },
    "proof": "`npm run e2e` in a scaffolded app IS the canonical proof of the whole loop: offline write -> sync -> edge admission -> cloud query. Path A (ws create + deploy) and Path B (ledger init + git push) end in the same place - all holons are equal in authority; the chain proves itself either way.",
    "reference": "No separate docs site yet - BY DESIGN the scaffold README is the tutorial and the installed @githolon/dsl + @githolon/client SOURCE is the reference. Reading it is the intended path (the license covers use, not redistribution). Gaps, questions, or want the kernel source? jack@captainapp.co.uk",
    "help": "`npx githolon --help` works ANYWHERE (no install needed) and lists every lane; every refusal names its remedy. The raw HTTP/git surface is the endpoint map below - everything the CLI does, curl and stock git can do."
  },
  "endpoints": {
    "POST /v1/workspaces/:ws[?tier=heavy]": "create a workspace (boots a holon: bootstrap → nomos controller). tier=heavy runs it in a dedicated 12GiB container (co2-scale law + data). Returns workspaceSecret ONCE — save it",
    "POST /v1/workspaces/:ws/set-tier?to=edge|heavy": "move the workspace between tiers (owner) — state-free re-mount from the ledger",
    "POST /v1/workspaces/:ws/domains": "deploy a policy (Authorization: Bearer <workspaceSecret>) — body is the .usda package, or nomos-compile's deploy JSON {packageUsda, readManifest, identityManifests} (package + per-workspace manifest overlay in one deploy); returns its content hash + Active installation",
    "GET  /v1/workspaces/:ws": "status",
    "GET  /v1/workspaces/:ws/domains": "the installed law — every domain-installation with phase/hash",
    "POST /v1/workspaces/:ws/domains?dryRun=1": "validate a package + manifest overlay WITHOUT installing (open)",
    "POST /v1/workspaces/:ws/rotate-secret": "rotate the workspace secret (Bearer = current secret); claims a legacy workspace",
    "POST /v1/workspaces/:ws/retire": "owner-gated retirement (Bearer = workspaceSecret) — stops quota contribution, data retained per the license (deploys + session pushes refuse; reads keep serving)",
    "GET  /v1/workspaces/:ws/dead-letters": "the workspace DLQ — domain-rejected intents, full provenance (owner)",
    "POST /v1/workspaces/:ws/dead-letters/retry?id=": "re-admit dead-lettered intents after a law fix — the unjam (owner)",
    "DELETE /v1/workspaces/:ws/dead-letters?id=": "explicitly discard dead letters (owner)",
    "GET  /v1/workspaces/:ws/counts/:countId?group=": "a declared count's maintained O(1) value",
    "GET  /v1/workspaces/:ws/sums/:sumId?group=": "a declared sum's maintained O(1) total",
    "GET  /v1/workspaces/:ws/manifests": "the workspace's effective read/identity manifests (baked ∪ deploy overlays)",
    "POST /v1/root/governance": "author a governance directive (grants, revocations, lifecycle) — admin AdminGrant required; the cloud governs itself",
    "GET  /v1/root/workspaces": "the law-state workspace registry (admin)",
    "GET  /health": "liveness",
    "GET  /v1/workspaces/:ws/aggregates/:id": "read an aggregate from the projection",
    "GET  /v1/workspaces/:ws/query?queryId=&params=": "run a domain query",
    "GET  /v1/workspaces/:ws/snapshot": "pull the holon state (browser-holon hydration bytes)",
    "GIT  /v1/workspaces/:ws/git": "the workspace ledger as a git remote — clone/pull/push with any git client",
    "GIT  push-to-create (the upload birth)": "pushing refs/heads/main to an UNBORN workspace births it FROM YOUR REPO: `githolon git remote <ws> && git push nomos main` (the CLI's credential helper answers the 401 challenge: username = your session token, password = the workspace secret it minted for you). Raw lane: `git remote add cloud https://<accessToken>:<yourChosenWorkspaceSecret>@…/v1/workspaces/<ws>/git && git push cloud main`. The holon replay-verifies the WHOLE chain from genesis (it executes, and thus validates, itself) before the workspace serves anything; a refused chain is archived under refs/heads/refused/. sha256(password) becomes the owner credential on the law record (no password = born open; claim via rotate-secret)",
    "POST /v1/workspaces/:ws/upload-verify": "re-run an upload birth's self-verification (a birth push schedules it automatically); GET /v1/workspaces/:ws shows phase + verdict"
  }
}