xitok 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Versions follow [Semantic Versioning](https://semver.org). Releases are cut by release-please from
+[Conventional Commits](https://www.conventionalcommits.org); see `docs/RELEASING.md`.
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- `xitok init`, `discover`, `add`: set up a project from what an agent would find — OpenAPI, docs
+  platform, llms.txt, MCP, SDKs — with a library of ready-made journeys.
+- `xitok run`: real agents (Claude Code; Codex, Gemini, OpenCode and Cursor experimental) in clean
+  rooms, several trials each, every outcome verified by running it; Wilson intervals; a signed
+  report.
+- `xitok ci` and the GitHub Action: change-aware smoke runs on pull requests, pooled baselines,
+  Fisher's exact test for regressions, one sticky PR comment, annotations, JUnit.
+- Docker sandbox with an egress allowlist.
+- Model matrix, flakiness detection, an optional LLM judge that never counts, AXIS import.
+- `xitok ui`: a local dashboard.

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0 (ELv2)
+
+Copyright (c) 2026 Lynt-X Global
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you with
+a notice of your violation, and you cease all violation of this license no later
+than 30 days after you receive that notice, your licenses will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any
+additional violation of these terms will cause your licenses to terminate
+automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion of
+it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,432 @@
+# XitOK
+
+**XitOK** (pronounced *exit OK*) tests your API with real AI coding agents — Claude Code, Codex,
+Gemini, OpenCode, Cursor — the way a brand-new developer's agent would meet it: in a clean room,
+many times, with every outcome **verified by running it**, and a signed report you can prove.
+Part of the [Lyntway](https://lyntway.com) family.
+
+```
+  XitOK score  57.5 / 100   grade D
+  ────────────────────────────────────────────────────────────────────
+  Journey                          claude-code             codex
+  Make a first authenticated call  100% 4/4 [51–100]       25%  1/4 [5–70]
+  Verify a webhook signature       100% 4/4 [51–100]       0%   0/4 [0–49]
+```
+
+## Quick start
+
+```bash
+npx xitok init      # discovers your API, writes xitok.yaml and a first journey
+npx xitok doctor    # checks agents and keys
+npx xitok run       # runs journeys × agents × trials and scores the result
+```
+
+Try it with no API keys: `cd examples/demo && npx xitok run` (two scripted agents stand in for real ones).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `xitok init` | Discovers your API (OpenAPI, docs platform, llms.txt, MCP, SDKs), writes `xitok.yaml`, a first journey, and a webhook-security journey when your spec has webhooks |
+| `xitok check <docs-url>` | Free preview of how ready a public docs site is for agents: readable without JavaScript, llms.txt, Markdown, OpenAPI, robots.txt, page weight… with what to fix first. Static checks, no agents, no signup |
+| `xitok discover` | Shows what an agent would find in your repo — and, with `--docs-url`, every public-docs check from `xitok check` |
+| `xitok add [template]` | Adds a ready-made journey: first call, no hardcoded secrets, secret key kept server-side, webhook signatures, current SDK version, idempotent create, rate-limit backoff (tested against a real 429), outcome on the live API, MCP tool use (`--list`) |
+| `xitok run` | Runs every journey with every agent, several trials each, in clean rooms, with a live progress matrix; `--models` for a model matrix |
+| `xitok watch` | Re-runs the journeys a change affects every time you save (1 trial by default, a per-session spend cap, runs never overlap) |
+| `xitok setup-agent <claude-code\|cursor\|codex>` | Teaches your coding agent to run XitOK and fix what it finds (a skill, a Cursor rule, or an AGENTS.md section). Claude Code plugin: `/plugin marketplace add xitokhq/xitok` then `/plugin install xitok@xitok` for `/xitok:run`, `/xitok:fix`, `/xitok:journey` |
+| `xitok setup-ci <provider>` | Writes the XitOK pipeline for GitHub Actions (pull requests, nightly baseline, new models), GitLab CI, CircleCI or Buildkite |
+| `xitok ci` | CI mode: runs only the journeys a change affects (or `--mode full`), compares with the baseline, annotates the PR, posts one sticky comment, writes the job summary |
+| `xitok draft` | Claude proposes new journeys from your spec and docs; only ones with a check that runs are kept, written as drafts you review and rename before they count |
+| `xitok import axis [path]` | Imports Netlify AXIS scenarios: the rubric becomes a judge check, checks that run are derived where the rubric states something checkable, and the rest become drafts that say what to add |
+| `xitok flaky` | Journey × agent pairs that pass only some of the time across recent runs, with the most common cause |
+| `xitok generate <llms-txt\|agents-md\|skill>` | Drafts `llms.txt`, an `AGENTS.md` for your users' repos, or a Claude Code skill — from your OpenAPI spec, the rules your journeys enforce, and the mistakes agents made in your latest run |
+| `xitok docs init <mintlify\|scalar\|fern\|readme\|in-repo>` | Writes a docs site into your repository for an API that has none — drafted from your spec, the rules your journeys enforce and what agents got wrong. No account, nothing published |
+| `xitok spec draft` | Reads your code and drafts an OpenAPI document from the routes it finds, marked a draft in three places because nobody has checked it yet |
+| `xitok upgrade --from <old spec>` | Compares two versions of your API and writes the migration as a skill agents follow: what breaks, what to change, and what it could not see. `--fail-on-breaking` stops a release that breaks callers |
+| `xitok badge` | An SVG badge for your README: the score and grade, or `--agent` for one agent's pass rate; says "custom" unless the standard panel ran. `xitok ci` writes one too |
+| `xitok models check` | What's new at Anthropic, OpenAI and Google since the last check; `--run` tests each new model side by side with the one you pin (daily workflow: `docs/ci/xitok-new-models.yml`) |
+| `xitok compare <baseline> [current]` | Which journey × agent pairs regressed or improved, with Fisher's exact test so noise isn't called a regression |
+| `xitok baseline set / show` | Promotes a run to the baseline that `xitok ci` compares against |
+| `xitok ui` | Opens the dashboard for this project's runs: score trend, journeys × agents matrix, every trial's checks and full transcript — and a journey editor with live validation, a preview of what will run, and one-click promotion of reviewed drafts (`--read-only` to turn editing off). Local only (127.0.0.1) |
+| `xitok report [path]` | Shows a past run (terminal, `--format md` for PR comments, `--format json`, or `--format junit`) |
+| `xitok verify <report>` | Verifies a signed report offline; `--trust <keyId>` to also check who signed it |
+| `xitok doctor` | Checks Node, config, agents, keys, the signing key, and Docker when the sandbox is on |
+| `xitok schema` | Writes JSON Schemas so editors autocomplete `xitok.yaml` and journeys |
+| `xitok completion <shell>` | Shell completions for bash, zsh and fish — commands, options, and journey ids from your project |
+
+Every command accepts `--json`.
+
+**Exit codes** — `0` ok · `1` score below `--fail-under`, a significant regression, or signature invalid · `2` invalid input or config · `3` nothing could run / interrupted.
+
+## In CI
+
+```yaml
+# .github/workflows/xitok.yml — full examples in docs/ci/
+- uses: xitokhq/xitok/action@v0
+  with:
+    mode: changed          # only journeys whose `watch` globs match the diff
+    fail-under: 70
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+`xitok ci` recognises GitHub Actions, GitLab CI (a note on the merge request with
+`XITOK_GITLAB_TOKEN`, results in the merge request's test report), Buildkite (the summary as the
+build annotation) and CircleCI; `xitok setup-ci <provider>` writes the pipeline.
+
+On a pull request XitOK runs a small smoke suite for the journeys the change touches, compares
+with the last few `main` baselines pooled, and posts one comment that it updates on every push. A
+drop only fails the build when it is statistically significant (`ci.regressionAlpha`, default
+0.1); smaller drops are reported as *dropped* without failing. Pairs that pass only some of the
+time are labeled *flaky*: pooling gives them a baseline that is that mix, so they don't raise false
+alarms. Nightly, `mode: full` runs everything and adds itself to the baseline history.
+
+## Panels: which agents, which exact models
+
+A score only means something if you know exactly what produced it. A **panel** is a versioned
+lineup with pinned model versions:
+
+```yaml
+panel: standard     # XitOK Standard Panel 2026.09: Claude Code + claude-sonnet-5,
+                    # Codex + gpt-5.3-codex, Gemini CLI + gemini-3.5-flash
+```
+
+`panel: frontier` runs the strongest models instead; `--panel` works on `run`, `ci` and `watch`.
+Public scores and badges use the standard panel. Choosing your own `agents` makes a *custom
+lineup*, and reports say so. Every report records the model each agent actually ran (including a
+switch mid-run), and `xitok doctor` warns about model aliases that can change silently and about
+models whose origin your security team may need to review ([ADR 0003](docs/adr/0003-model-panels-and-origin-policy.md)).
+
+## Model matrix
+
+Which model does your API work best with? List several and each becomes its own column, with a
+head-to-head that says which differences are real:
+
+```yaml
+agents:
+  - id: claude-code
+    models: [claude-opus-5, claude-sonnet-5, claude-haiku-4-5]
+```
+
+Or ad hoc: `xitok run --models claude-code:claude-opus-5,claude-code:claude-haiku-4-5`. Pull
+request smoke runs use only the first model.
+
+## Agent-to-agent (A2A)
+
+If you ship an agent, test whether other agents can use it. An `a2a` journey gives the coding agent
+a bridge to your agent over the Agent2Agent protocol (1.0 and 0.3), and XitOK verifies from its own
+record of the traffic — not the coding agent's claim — that your agent took the task to the state
+you expect:
+
+```yaml
+context:
+  policy: a2a
+  agentCardUrl: https://agent.acme.com          # or the card's URL
+  agentHeaders: { authorization: "Bearer ${ACME_AGENT_TOKEN}" }
+verify:
+  - type: a2a
+    expectState: completed
+    replyContains: confirmed
+```
+
+`xitok add a2a-task` starts one; `xitok check` reports whether your site publishes an agent card.
+
+## LLM judge (optional, never counted)
+
+Some qualities can't be checked by running code — is it idiomatic, is the explanation right? Add a
+judge check and Claude grades the work against your rubric:
+
+```yaml
+verify:
+  - type: command          # verified: decides pass or fail
+    run: node send.js
+  - type: judge            # judged: recorded, never counted
+    rubric: Uses the official Acme SDK, not raw HTTP, and reads the key from the environment.
+    files: ["**/*.js"]     # optional; default is every text file in the workspace
+```
+
+The judge uses `XITOK_JUDGE_API_KEY` or `ANTHROPIC_API_KEY` and `judge.model` (default
+`claude-sonnet-5`); without a key, judged checks are skipped. Everything it is shown is redacted
+first, and agent output is marked as data so the agent can't instruct its own grader. Every report
+that used a judge says how often it agreed with the execution-verified outcome — the reason XitOK
+scores on execution, not opinion. Judge tokens are recorded in the check's evidence; their cost is
+not part of the agent spend.
+
+## Sandbox
+
+By default trials run as local processes in a clean room. For untrusted code, or when you want a
+hard network boundary, run every agent and every check in a container:
+
+```yaml
+sandbox:
+  kind: docker
+  image: xitokhq/runner:latest   # docker/runner/Dockerfile
+  network: allowlist           # allowlist | none | open
+  allow: [api.acme.com]        # added to the agent's model API, package registries and your docs
+  inspect: [api.acme.com]      # optional: record which endpoints agents actually called
+```
+
+With `allowlist`, the container sits on an internal Docker network whose only way out is an egress
+proxy that admits listed hosts on ports 80/443 and refuses everything else; direct connections have
+no route. Every refused host is recorded in the report. Containers run as your user, with all Linux
+capabilities dropped, `no-new-privileges`, and CPU, memory and process limits; the project is
+mounted read-only. Secrets reach the container through a private env file deleted after each
+command (or, for multi-line values, the docker CLI's own environment) and never appear in process
+arguments.
+
+### Shared journey libraries
+
+One project's journeys can be inherited by others in the same organization — a security suite
+every team must pass, kept private to you rather than published:
+
+```yaml
+libraries:
+  - project: prj_security          # a project in your org, marked as a library
+    journeys: [webhook-*]          # optional; omit to inherit all of them
+```
+
+Your own journeys win on a clash, and so does an earlier library: a shared suite can add checks
+but never silently replace one of yours. A reference that matches no journey is an error rather
+than a quiet no-op, because a run that skipped a security suite still reports as passed.
+
+Libraries are resolved by XitOK Cloud, which is the only place that can see another project. A
+local `xitok run` says so instead of testing less than the file asks for.
+
+### Already have a Postman collection?
+
+```bash
+npx xitok import-postman ./acme.postman_collection.json
+```
+
+Each folder becomes a journey, and every request becomes a line of what that journey has to
+achieve. Most teams have a collection and no OpenAPI spec, so this is usually the fastest way in.
+
+**The collection never reaches the agent.** It tells XitOK what the API is and which endpoints
+exist; the agent still has to work out the endpoints, the auth and the payloads from your
+documentation. A prompt containing the method and path would measure replay, not discovery.
+
+Those recorded endpoints are useful twice: they become the ground truth the
+[endpoint ledger](#the-endpoint-ledger) is compared against, so an agent calling something that
+does not exist is a finding you can prove rather than infer.
+
+Collections routinely hold live keys. Variable **names** carry over as journey secrets; values
+are never read.
+
+Journeys arrive as `.yaml.draft` with a placeholder verifier you must replace — only you know what
+success means for your API, and a check that passes without confirming anything proves nothing.
+
+### Hand someone the evidence
+
+```bash
+npx xitok pack .xitok/runs/<run>/report.json
+```
+
+Writes a folder that answers the four questions a sceptical reader asks, in the order they ask
+them — **what was tested**, **what happened**, **where data went**, **who vouches** — plus the
+signed report and every transcript.
+
+Nothing in it needs XitOK. The signature verifies offline from inside the folder, and each page
+states its own limits: a local run says plainly that no egress was recorded, an uninspected run
+says which endpoints are unknown *and that this is a gap in the pack rather than a finding about
+your product*, and a rate is never shown without the interval the trial count actually supports.
+
+It is for the people who cannot check your work any other way: an auditor, a customer's security
+reviewer, a buyer in diligence.
+
+### Get a second party to vouch for a result
+
+A XitOK report is signed by whoever ran it, which shows the content has not changed and nothing
+more. `xitok attest` has [Lyntway](https://lyntway.com) counter-sign the same claim:
+
+```bash
+LYNTWAY_API_KEY=... npx xitok attest .xitok/runs/<run>/report.json
+```
+
+```
+✓ Attested by Lyntway
+Receipt  rcpt_b93bfbb12d602dfdd079ad0a
+Covers   sha256:a1d3f2191924ab74…
+Evidence attested by Lyntway
+```
+
+The receipt names the report's content digest, so it is bound to exactly one report — and writing
+it back does not disturb the signature, because neither the signature nor the attestation is part
+of what was signed.
+
+**What a receipt proves, stated plainly:** Lyntway received this report, naming this content, at
+this time. It is not a claim that Lyntway checked the run. That is still worth having — a
+timestamp and a signature from a party with no stake in the result — and overstating it would cost
+more than it is worth.
+
+### Ask XitOK from inside your agent
+
+`xitok mcp` serves XitOK's read-only tools over MCP, so an agent can ask what it is about to build
+on before it writes a line:
+
+```json
+{ "mcpServers": { "xitok": { "command": "npx", "args": ["-y", "xitok", "mcp"] } } }
+```
+
+The agent gets one tool, `xitok_check_docs`: give it a documentation URL and it returns what
+passed, what will trip an agent up, and what to fix first. The answer carries its own limits —
+*"no agents were run, so this is not a XitOK score"* — in the payload, not in documentation the
+agent will never read.
+
+The surface is read-only on purpose. A tool that could start billable runs is a tool an agent
+could spend your money with, unattended.
+
+### Running a build you already have
+
+The Action fetches XitOK from npm by default. Point `command` at a build instead — to pin one you
+made yourself, or to exercise the Action against a checkout:
+
+```yaml
+- uses: xitokhq/xitok/action@v0
+  with:
+    command: node ./apps/cli/dist/index.js
+```
+
+XitOK's own CI uses this to run the Action on every pull request, so the Action is tested before a
+release exists rather than after the first customer finds out.
+
+### Running on a cloud you already pay for
+
+Point XitOK at Microsoft Foundry or Amazon Bedrock and the model spend draws down against
+commitments you already have, under procurement you have already done:
+
+```yaml
+provider:
+  kind: foundry                    # foundry | bedrock | direct
+  location: acme-ai                # Azure resource name, or an AWS region
+  models:
+    claude-code: acme-opus-prod    # required — see below
+```
+
+The credential is a single environment variable — `ANTHROPIC_FOUNDRY_API_KEY` or
+`AWS_BEARER_TOKEN_BEDROCK` — which is what a clean room with an isolated home directory can
+carry. The sandbox allowlist follows, so agents reach your cloud and not the vendor.
+
+**Pinning a model is required, not optional.** An unpinned alias resolves to the agent CLI's own
+default, and Bedrock quietly falls back to an older or smaller model when that default is not
+enabled in your account. A signed score against a model that never ran is the one result XitOK
+must never produce, so it refuses to start instead.
+
+Two differences are recorded in the report rather than smoothed over, because they change what a
+score means: agents on Bedrock have no web search, and a Foundry deployment name is asserted by
+your Azure configuration rather than observed by XitOK. A score is comparable to another only
+when these match.
+
+### Model traffic through the Lyntway gateway
+
+XitOK does not run its own model gateway. Point it at [Lyntway](https://lyntway.com) and every
+model call an agent makes is metered, capped and recorded with a signed receipt:
+
+```yaml
+gateway:
+  url: https://gateway.lyntway.com   # unset = agents call their providers directly
+  tokenEnv: LYNTWAY_API_KEY          # the variable holding the key, never the key
+  requirePassthrough: true           # refuse a trial the gateway altered
+```
+
+Each agent's own client is repointed at `<url>/gw/<provider>` and given a bearer token; its
+provider key is dropped from the clean room, and the sandbox allowlist stops admitting the
+provider's host, so there is no route around the thing doing the metering.
+
+Two things are worth understanding before you turn it on.
+
+**Only model traffic goes this way.** Calls to the API under test stay on XitOK's own egress
+proxy. XitOK measures a stranger's experience of your product, and a governing hop in between
+would make the grade mean something else.
+
+**The gateway tenant must be pinned to log-only.** Journeys carry synthetic API keys and example
+addresses on purpose, and Lyntway's default policy blocks a credential and tokenises personal
+data — so a default-configured tenant refuses a normal XitOK prompt outright, and a differently
+configured one could rewrite it and have XitOK grade a run the agent never saw. With
+`requirePassthrough` (the default), XitOK reads Lyntway's own `X-Lyntway-Decision` and
+`X-Lyntway-Mode` on every call and refuses to treat an altered one as a measurement.
+
+### The endpoint ledger
+
+Name your own API under `inspect` and the report gains an **endpoint ledger**: every call the
+agents actually made, as method, path and status.
+
+```
+Endpoints 2 distinct on api.acme.com
+     7× POST   /v1/send → 201
+     3× GET    /v1/messages?limit → 404
+```
+
+That is observation, not the agent's own account of itself — which is what makes it evidence that
+an endpoint was hallucinated, or that a journey never reached your API at all.
+
+XitOK terminates TLS inside the sandbox to see this, so it is **off until you opt a host in**, and
+bounded deliberately:
+
+- Only hosts you name. Everything else stays an opaque tunnel.
+- **Model providers can never be inspected**, whatever you put in `inspect`. Your model keys and
+  the agent's reasoning are unreadable to XitOK by construction, not by promise.
+- **Method, path and status only.** Headers and bodies are piped through unread, query-string
+  values are dropped (the keys are kept), and your secrets are redacted from paths.
+- The certificate authority is minted per run, never written to disk outside the clean room, and
+  expires with the run. The proxy only ever holds the leaf certificates for the hosts you named.
+
+The ledger always lists the hosts it did *not* inspect, so an empty ledger can never be misread as
+"the agent called nothing". See [ADR 0006](docs/adr/0006-endpoint-ledger-and-tls-inspection.md).
+
+## When something fails
+
+Every failed trial gets a cause (authentication, wrong endpoint, outdated SDK, security, crash,
+gave up…) from deterministic rules over its evidence, and every run ends with **how to fix** it:
+what to change in your docs, SDK or error messages, quoting the evidence — the endpoint agents
+guessed, the SDK version they installed, the error they hit. Test-setup problems (a missing key)
+are kept apart, so nobody edits their docs to fix a CI secret.
+
+If you edit a journey, its results start fresh: comparisons only pool runs of the same journey
+version, so a harder test is never reported as a product regression.
+
+## How results stay honest
+
+- **Clean room.** Each trial gets a fresh workspace and a fresh `HOME`. No personal agent memory,
+  config, MCP servers or credentials are visible. Claude Code runs in `--bare` mode.
+- **Verified, not judged.** A trial passes only when execution-based checks pass (commands, files,
+  HTTP, transcript facts). An LLM judge, when enabled, is labeled *judged* and never counts.
+- **Errored ≠ failed.** Missing keys, missing agents, sandbox problems, or an agent that fails
+  before making a single tool call (a bad model name, its provider down) are excluded from the
+  score and reported separately — they say nothing about your product.
+- **Statistics.** Pass rates come with 95% Wilson confidence intervals.
+- **Secrets never leave.** Keys are redacted at the source, before anything is written.
+- **Signed.** Reports are signed with Ed25519 over canonical JSON; `xitok verify` works offline.
+
+The complete, versioned methodology — outcomes, statistics, the score formula, panels, comparisons,
+flakiness and evidence: [docs/METHODOLOGY.md](docs/METHODOLOGY.md). Design: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Every planned
+feature: [docs/FEATURES.md](docs/FEATURES.md). Phases: [docs/ROADMAP.md](docs/ROADMAP.md).
+
+## Repository
+
+```
+packages/spec     schemas for config, journeys and reports (zod → JSON Schema)
+packages/agents   headless adapters for each AI coding agent
+packages/core     discovery, clean rooms, runner, verifiers, scoring, reports, signing
+apps/cli          the `xitok` command (bundles the dashboard)
+apps/web          the dashboard (React), served by `xitok ui`
+examples/demo     a project that runs with scripted agents and no keys
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm check                                   # lint + build + typecheck + all tests
+pnpm pack:smoke                              # the published package, installed and used on its own
+ANTHROPIC_API_KEY=... pnpm --filter @xitok/agents test:integration   # real Claude Code, a few cents
+docker build --build-arg AGENT_PACKAGES= -t xitok/runner:test docker/runner
+pnpm --filter @xitok/core exec vitest run test/docker.int.test.ts     # real Docker sandbox
+```
+
+Requires Node 22+ and pnpm 10, on macOS or Linux (on Windows, use WSL 2). Contributing: [CONTRIBUTING.md](CONTRIBUTING.md). Releases:
+[docs/RELEASING.md](docs/RELEASING.md).
+
+## License
+
+[Elastic License 2.0](LICENSE). Use it, modify it, redistribute it. The one thing it forbids is
+offering XitOK to third parties as a hosted or managed service.