{"owner":"withcoral","repo":"coral","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Repo Map\n\n- `crates/coral-api`: protobuf contract and generated Rust bindings.\n- `crates/coral-app`: local server composition, state, workspaces, source\n  lifecycle, and workspace-scoped catalog discovery behavior.\n- `crates/coral-cli`: terminal adapter.\n- `crates/coral-client`: intentionally thin transport bootstrap plus\n  Arrow IPC decode/render helpers.\n- `crates/coral-engine`: engine-side backend compilation, runtime registration,\n  and query execution.\n- `crates/coral-mcp`: MCP tool core with stdio and Streamable HTTP transport\n  adapters over `coral-client`.\n- `crates/coral-spec`: declarative source-spec parsing, validation,\n  input discovery, and normalized source-definition models.\n- `crates/coral-telemetry`: cross-crate telemetry helpers that are independent\n  of app bootstrap, query runtime, and adapter surfaces.\n- `apps/desktop`: Electron shell around Reef and the local Coral sidecar.\n- `apps/docs`: Mintlify documentation site.\n- `apps/reef`: React Router/Wax frontend shell. It is validated independently\n  from `apps/ui` and is not built by Rust crate build scripts.\n- `apps/ui`: embedded Coral app UI built into the CLI release flow.\n- `plugins/coral`: Agent plugin packaging. `plugins/coral/skills` is the\n  canonical in-repo home for maintained Coral agent skills.\n\n## Rules\n\n- Run `make rust-checks` before submitting PRs that include changes to Rust code.\n- For Postgres-backed database changes, run `make postgres-tests`. Keep this as\n  the single entry point for local and CI Postgres coverage; do not duplicate\n  its Cargo test invocations in workflows or contributor instructions. The\n  target uses `CORAL_TEST_POSTGRES_URL` when supplied. Otherwise it starts a\n  local Docker Postgres and creates a fresh database inside the reusable\n  container. Docker chooses an available localhost port by default; use\n  `make postgres-url` to print the server URL or\n  `LOCAL_POSTGRES_PORT=55432 make postgres-start` when you need a stable port.\n  Use `make postgres-start` when you only need the server,\n  `make postgres-stop` when finished, and `make postgres-clean` to remove the\n  reusable container.\n- Run `make schema-check` before submitting PRs that touch generated manifest\n  schemas or the Rust helpers that generate them. Use\n  `make schema-generate` to refresh generated schema files. The Validate\n  workflow enforces this through its `schema-freshness` job when schema inputs\n  change.\n- UI changes must pass `npm run check --prefix apps/ui` (oxfmt + oxlint) before submitting.\n- Reef changes must pass `npm run check --prefix apps/reef`,\n  `npm run typecheck --prefix apps/reef`, `npm test --prefix apps/reef`, and\n  `npm run build --prefix apps/reef`, followed by\n  `npm run test:server --prefix apps/reef`, before submitting. The production\n  server smoke test consumes the build output and runs on every Reef CI job.\n- Desktop changes must pass `npm run check --prefix apps/desktop` and\n  `npm test --prefix apps/desktop` before submitting.\n- Keep Reef Vitest coverage Node-only and focused on atomic deterministic\n  functions and policies or explicit architectural invariants. Do not add broad\n  browser, router, or framework-plumbing tests without a named contract or\n  regression they protect.\n- Use Storybook and Chromatic for Reef component visual states.\n- Reef styling uses vanilla-extract; do not introduce Tailwind.\n- Run `make perf-check` before submitting PRs that could affect CLI startup,\n  local server bootstrap, source registration, or `coral.tables` catalog query\n  latency. CI installs the bundled `github` source with fake credentials and\n  fails when release `coral sql \"select * from coral.tables\"` has a hyperfine\n  mean above 750 ms.\n- Pull requests do not automatically build macOS Desktop packages. Use manual\n  dispatch for an unsigned packaging preflight when a distribution-sensitive\n  change warrants one. Validation artifacts stay unsigned and must not be\n  reused for a release; Desktop release publishing must rebuild from a clean\n  checkout with signing and notarization.\n- The `Validate` workflow intentionally skips draft pull request runs, starts\n  again on `ready_for_review`, and still triggers on `converted_to_draft` so the\n  replacement skipped run cancels any in-progress validation for the PR branch.\n  Keep that draft gate aligned between the initial change detector and final\n  aggregate `validate` job.\n- Keep Release Please branch updates coalesced and cheap to supersede. The\n  `release-please` workflow may create multiple local regeneration commits, but\n  must push them together through its final push step. `Validate` intentionally\n  gives `release-please--*` pull requests a 120-second settle period before\n  checkout and change detection so concurrency cancellation stops intermediate\n  branch states before expensive jobs fan out.\n- `make rust-checks` is the Rust-only local gate and should keep using\n  `--all-features`; the embedded UI feature is a normal CLI build surface.\n- The built UI artifact is produced by repo/CI orchestration (`make ui-build`\n  or the `UI build` workflow job), not by `crates/coral-cli/build.rs`. Local\n  Rust builds may compile without `apps/ui/dist`, because UI development normally\n  serves assets from Vite while the CLI provides the loopback API server.\n- Use `make docker-build` to compile the current checkout in a native Linux\n  BuildKit stage and package that binary as `coral:local`. Set\n  `DOCKER_IMAGE=coral:test` to change the local tag or `DOCKER_NO_CACHE=1` to\n  bypass Docker layer caching. Keep the exported-binary layout and runtime\n  platform aligned with the `docker-publish` workflow; local Docker-exporter\n  loads disable provenance because that exporter cannot load attestation\n  manifests. Local builds must not download a published Coral binary.\n- Use `make reef-docker-build` to build Reef from the current checkout and\n  `make reef-docker-smoke` to run the configuration matrix against an\n  already-built Reef image. Use the self-contained `make reef-docker-test` for\n  both. That matrix is peer-free: it asserts which runtime configurations boot\n  and which fail fast, while readiness against a live Coral is covered by the\n  mocked health client in `apps/reef/app/routes/readyz.server.test.ts`.\n- Use `make coral-docker-stub-test` to build the Coral image with a stub binary\n  and exercise `docker/entrypoint.sh` (config seeding, seed-once semantics, and\n  the unwritable-volume failure). The entrypoint is pure shell up to its closing\n  exec, so this needs no Rust build; the real binary is covered by\n  `make rust-checks` and the real image by the release smoke in\n  `.github/workflows/docker-publish.yml`. Reef's runtime stage must remain COPY-only and\n  non-root; build and dependency stages run on the build platform. Local builds\n  follow the Docker daemon's architecture, while CI builds and verifies\n  linux/amd64 only. TLS termination belongs to the operator and is\n  not provisioned by the image or its smoke harness.\n- Keep adapters thin. If CLI or MCP behavior gets complex, move it inward.\n- Keep server topology orchestration private to `coral-cli` while CLI commands\n  are its only consumers. Do not extract the orchestration into a shared\n  orchestration crate unless it gains a non-CLI consumer; the combined topology\n  is provisional and may be removed rather than promoted.\n- Keep transport contract concerns in `coral-api`, source-spec concerns in\n  `coral-spec`, app/state concerns in `coral-app`, and query/runtime\n  concerns in `coral-engine`.\n- Keep app-owned runtime package assembly in `coral-app`. `coral-engine`\n  should compile generic runtime components, not interpret DSL v4 authored\n  manifests, materialized fingerprints, semantic IR, or projection catalogs.\n- Keep Reef Coral access behind React Router server loaders, actions, or\n  resource routes using `apps/reef/app/lib/coral-request.server.ts`. Do not\n  expose a generic renderer-to-Coral transport or Desktop sidecar proxy; add an\n  explicit server route when browser-triggered Coral behavior is needed.\n- The packaged Reef server resolves its external runtime packages from the\n  Electron app. Keep every `apps/reef` production dependency represented in\n  `apps/desktop` production dependencies; the desktop config tests enforce this\n  packaging contract.\n- Use `CORAL_DESKTOP_APP=1` as Reef's single external desktop build marker.\n  React Router route composition may read it from `process.env`, while\n  `apps/reef/vite.config.ts` exposes only its compiled boolean value as\n  `import.meta.env.CORAL_DESKTOP_APP`. Do not add a parallel\n  `VITE_CORAL_DESKTOP_APP` marker or expose broader `CORAL_*` values to browser\n  code.\n- For DSL v4 materialization, the user owns when a source is generated or\n  regenerated. Coral materializes at source add, queries only from the\n  installed materialized package, and never silently refreshes descriptors,\n  projections, or persisted artifacts. Treat fingerprints, producer versions,\n  identity metadata, and raw-document hashes as advisory provenance: report\n  mismatches through tracing, but load readable, structurally compatible\n  artifacts. Isolate source-local compatibility failures without hiding\n  operational failures.\n- A DSL v4 source declares top-level `inputs:` and exactly one singular\n  `surface:`. The source `name` is its SQL namespace. Do not add surface ids,\n  namespace suffixes, or multiple surfaces to one manifest; represent distinct\n  provider interfaces as distinct source specs instead.\n- Keep cross-crate W3C trace-context propagation helpers in\n  `coral-telemetry`; do not make `coral-app`, `coral-client`, `coral-engine`,\n  or `coral-mcp` depend on each other just to share telemetry carrier logic.\n- Keep shared Arrow IPC decoding and result rendering in `coral-client`.\n- Treat `coral-app` as an internal composition root even if sibling crates use\n  its bootstrap seam today.\n- If a caller needs explicit local server control, prefer `coral-client::local`\n  over widening the default client surface.\n- Keep process environment access owned by the right crate. `coral-app` owns\n  runtime/bootstrap env reads, `coral-cli` owns CLI-surface env reads, and\n  other crates should receive explicit values from callers instead of reading\n  ambient process environment directly.\n- Keep docs lean and readable. For CLI or MCP changes, update `apps/docs/` only\n  when the change affects a public surface or captures important user-facing or\n  contributor-facing knowledge. Do not document every implementation detail.\n  When docs are warranted, choose the best existing location first and make the\n  amount of space match the feature's user-facing weight and visibility.\n- Keep stable bundled sources under `sources/core/**`; put preview DSL v4 source\n  specs under `sources/v4/[source]/manifest.yaml` with distinct manifest names\n  (defined in the manifest's `name` field) such as `<name>_v4`. When a provider\n  has distinct interfaces, use sibling source directories such as `github` and\n  `github_mcp`. Do not bundle\n  `sources/v4` into the binary; install preview v4 sources with\n  `coral source add --file`. Do not replace or migrate an existing v3 source\n  merely because a preview v4 spec exists.\n- Changes to `scripts/install.sh` must keep the `Validate` workflow's\n  install-script matrix in sync with every OS/architecture target that the\n  installer supports.\n- Keep general repository automation in `xtask`; reserve `scripts/` for the\n  bash Coral installer and installer-specific support.\n- Keep `xtask` organized by workflow: docs generation lives under\n  `xtask/src/docs/`, shared source-manifest discovery lives in\n  `xtask/src/sources.rs`, command-latency checks live in `xtask/src/perf.rs`,\n  benchmark dispatch lives under\n  `xtask/src/benchmarks/`, and the isolated benchmark package and fixtures live\n  under `xtask/benchmarks/`. Skill export lives in `xtask/src/skills.rs`.\n  Release signing and notarization automation lives in `xtask/src/release.rs`.\n  The DSL v4 inference report lives in `xtask/src/metadata_report.rs`.\n- Use `cargo run --locked -p xtask -- benchmark list-columns` to measure the\n  complete MCP `list_columns` response for the checked-in synthetic wide-table\n  fixture with the `o200k_base` tokenizer. The benchmark must call the real MCP\n  tool in-process, report without enforcing a token budget, and keep\n  benchmark-only code out of production crates.\n- Use `cargo run --locked -p xtask -- v4-metadata-report` before and after a\n  change to DSL v4 row-path, pagination, or lookup-key inference, and diff the\n  two reports. It imports every non-MCP v4 source under `sources/v4` and emits\n  one CSV row per operation, so an unintended reshape in a source nobody was\n  thinking about shows up as a diff hunk. Pass `--cache-dir` so a before/after pair fetches\n  each descriptor once. It is deliberately not wired into CI: it fetches\n  multi-megabyte vendor descriptors over the network, and vendor descriptors\n  change under us, so a green run proves nothing about the commit that produced\n  it.\n- Universal Search relevance benchmarking also lives in the isolated\n  `coral-benchmarks` package. Keep real catalog inventories, generated\n  questions, collected queries, responses, focused corpora, and replay reports\n  under ignored run directories. Only synthetic, deliberately non-sensitive\n  benchmark fixtures may be checked in. Use frozen-query replay rather than\n  rerunning agents while tuning ranking weights, and do not run agent\n  collection in CI.\n- The Electron desktop app version is tied to the CLI release version through\n  release-please. The release workflow builds the macOS desktop app from\n  `apps/desktop`, uploads its DMG/ZIP/update metadata to the same GitHub\n  Release as the CLI artifacts, and the website should link to the\n  `releases/latest/download` DMG rather than storing desktop binaries itself.\n- `make docs-check` intentionally skips the aggregate community source catalog.\n  Any PR may leave that generated page stale so unrelated changes do not fail\n  on aggregate community catalog drift; keep docs freshness strict for bundled\n  sources under `sources/core/**`, `apps/docs/docs.json`, and the changelog.\n- The live docs site deploys from the long-lived `docs` branch, not `main`, so\n  the published catalog matches the latest released binary. `main` still owns\n  docs freshness, but merging to `main` no longer publishes the site by itself:\n  the release workflow advances `docs` after release artifacts are published.\n  See `apps/docs/AGENTS.md` for the full publishing model.\n- Keep checked-in generated files marked in `.gitattributes` with\n  `linguist-generated` so GitHub collapses them by default in PR diffs.\n- Source inputs that carry credentials must be `kind: secret`, never\n  `kind: variable`. This includes API keys, bearer tokens, access tokens,\n  passwords, private keys, authorization header values, and admin/read keys,\n  even when the credential is read-only or the source also supports anonymous\n  access.\n- When source credential retrieval or auth guidance changes, keep the source\n  spec docs and maintained Coral source-spec skills aligned in the same change.\n  OAuth source-spec behavior needs both reader-facing docs and agent-facing\n  author/review guidance because `credential.methods` controls setup while\n  `auth` still controls runtime requests.\n- Keep maintained Coral agent skills in `plugins/coral/skills`. External\n  distribution repos or packages should mirror from that directory rather than\n  becoming a separate source of truth. Use\n  `cargo run --locked -p xtask -- export-skills --dest <path>` for local\n  export checks and distribution syncs.\n- Keep `plugins/coral` conformant with Agent Plugins 1.0: portable metadata\n  belongs in root `plugin.json`, skills are discovered from `skills/`, and MCP\n  servers are declared in root `mcp.json`. Keep the legacy `.codex-plugin`,\n  `.mcp.json`, and `.app.json` package files for pre-0.147 Codex compatibility.\n  Put current Codex-only metadata under `extensions.com.openai`, and align shared\n  metadata and MCP invocation across both representations.\n- Coral skills must include `agents/openai.yaml`. Keep\n  `interface.display_name` in the form `Coral` or `Coral <Title Case Suffix>`,\n  keep the top-level `SKILL.md` heading equal to that display name, and set\n  non-empty `short_description` and `default_prompt` values. The default prompt\n  should mention the skill token, such as `$coral-create-source-spec`.\n- When proposing or updating a PR title, use Conventional Commits:\n  `type(scope): summary`.\n- When using a scope, prefer one that matches the primary area changed,\n  usually the crate name minus the `coral-` prefix, `docs`,\n  `sources/core/<name>`, or `sources/community/<name>`.\n- Keep the PR title up to date as the branch evolves. If the change shifts in\n  scope or intent, update the title to match the current final shape of the\n  branch.\n- Use `!` only for breaking changes, placing it immediately before the colon:\n  `type!: summary` or `type(scope)!: summary`. Local WIP commit messages can\n  stay pragmatic unless the user explicitly asks for polished commit history.\n- If you add a source using dummy credentials in order to test a change, always\n  configure Coral to store those credentials on the filesystem. Do not store\n  dummy credentials in the OS keychain.\n\n## Meta Changes\n\nA meta change modifies how contributors or agents should work in this repo, not\nonly runtime behavior. Examples include repo layout, crate ownership, source\ndirectory conventions, docs generation behavior, CLI/MCP surface rules, PR\ntitle/scope guidance, verification commands, and agent-facing review or\nsource-authoring instructions.\n\nFor meta changes:\n\n- Update the nearest relevant `AGENTS.md` in the same change.\n- Update `apps/docs/`, generated docs, or docs tooling only when the changed\n  behavior is user-facing or docs-authoring-facing, and use the smallest useful\n  edit in the best existing location.\n- Preserve provenance: keep observed repo facts, project direction, local\n  preferences, and generated context separate instead of merging them into one\n  untraceable rule.\n- Treat repeated human steering as a defect in the operating loop. Identify the\n  failure class, update durable context or tooling when that can prevent\n  recurrence, and verify the new rule before resuming unrelated work.\n- Include explicit validation showing the guidance matches the implemented\n  behavior.\n- Mention in the PR description what agent or contributor behavior changed.\n\n## What Counts As a Breaking Change for a CLI?\n\nFor a CLI, the user interface is the API.\n\nA change is breaking if it can break existing:\n\n- commands people run manually\n- scripts and CI jobs\n- documented workflows\n- integrations that parse output\n\nTreat these as stable contract surfaces:\n\n- command/subcommand names\n- flags and positional arguments\n- exit codes\n- structured output (for example JSON)\n- config file keys, format, and location\n- environment variables and precedence rules\n\nIf any of those change incompatibly, it is a breaking change.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Repo Map\n\n- `crates/coral-api`: protobuf contract and generated Rust bindings.\n- `crates/coral-app`: local server composition, state, workspaces, source\n  lifecycle, and workspace-scoped catalog discovery behavior.\n- `crates/coral-cli`: terminal adapter.\n- `crates/coral-client`: intentionally thin transport bootstrap plus\n  Arrow IPC decode/render helpers.\n- `crates/coral-engine`: engine-side backend compilation, runtime registration,\n  and query execution.\n- `crates/coral-mcp`: MCP tool core with stdio and Streamable HTTP transport\n  adapters over `coral-client`.\n- `crates/coral-spec`: declarative source-spec parsing, validation,\n  input discovery, and normalized source-definition models.\n- `crates/coral-telemetry`: cross-crate telemetry helpers that are independent\n  of app bootstrap, query runtime, and adapter surfaces.\n- `apps/desktop`: Electron shell around Reef and the local Coral sidecar.\n- `apps/docs`: Mintlify documentation site.\n- `apps/reef`: React Router/Wax frontend shell. It is validated independently\n  from `apps/ui` and is not built by Rust crate build scripts.\n- `apps/ui`: embedded Coral app UI built into the CLI release flow.\n- `plugins/coral`: Agent plugin packaging. `plugins/coral/skills` is the\n  canonical in-repo home for maintained Coral agent skills.\n\n## Rules\n\n- Run `make rust-checks` before submitting PRs that include changes to Rust code.\n- For Postgres-backed database changes, run `make postgres-tests`. Keep this as\n  the single entry point for local and CI Postgres coverage; do not duplicate\n  its Cargo test invocations in workflows or contributor instructions. The\n  target uses `CORAL_TEST_POSTGRES_URL` when supplied. Otherwise it starts a\n  local Docker Postgres and creates a fresh database inside the reusable\n  container. Docker chooses an available localhost port by default; use\n  `make postgres-url` to print the server URL or\n  `LOCAL_POSTGRES_PORT=55432 make postgres-start` when you need a stable port.\n  Use `make postgres-start` when you only need the server,\n  `make postgres-stop` when finished, and `make postgres-clean` to remove the\n  reusable container.\n- Run `make schema-check` before submitting PRs that touch generated manifest\n  schemas or the Rust helpers that generate them. Use\n  `make schema-generate` to refresh generated schema files. The Validate\n  workflow enforces this through its `schema-freshness` job when schema inputs\n  change.\n- UI changes must pass `npm run check --prefix apps/ui` (oxfmt + oxlint) before submitting.\n- Reef changes must pass `npm run check --prefix apps/reef`,\n  `npm run typecheck --prefix apps/reef`, `npm test --prefix apps/reef`, and\n  `npm run build --prefix apps/reef`, followed by\n  `npm run test:server --prefix apps/reef`, before submitting. The production\n  server smoke test consumes the build output and runs on every Reef CI job.\n- Desktop changes must pass `npm run check --prefix apps/desktop` and\n  `npm test --prefix apps/desktop` before submitting.\n- Keep Reef Vitest coverage Node-only and focused on atomic deterministic\n  functions and policies or explicit architectural invariants. Do not add broad\n  browser, router, or framework-plumbing tests without a named contract or\n  regression they protect.\n- Use Storybook and Chromatic for Reef component visual states.\n- Reef styling uses vanilla-extract; do not introduce Tailwind.\n- Run `make perf-check` before submitting PRs that could affect CLI startup,\n  local server bootstrap, source registration, or `coral.tables` catalog query\n  latency. CI installs the bundled `github` source with fake credentials and\n  fails when release `coral sql \"select * from coral.tables\"` has a hyperfine\n  mean above 750 ms.\n- Pull requests do not automatically build macOS Desktop packages. Use manual\n  dispatch for an unsigned packaging preflight when a distribution-sensitive\n  change warrants one. Validation artifacts stay unsigned and must not be\n  reused for a release; Desktop release publishing must rebuild from a clean\n  checkout with signing and notarization.\n- The `Validate` workflow intentionally skips draft pull request runs, starts\n  again on `ready_for_review`, and still triggers on `converted_to_draft` so the\n  replacement skipped run cancels any in-progress validation for the PR branch.\n  Keep that draft gate aligned between the initial change detector and final\n  aggregate `validate` job.\n- Keep Release Please branch updates coalesced and cheap to supersede. The\n  `release-please` workflow may create multiple local regeneration commits, but\n  must push them together through its final push step. `Validate` intentionally\n  gives `release-please--*` pull requests a 120-second settle period before\n  checkout and change detection so concurrency cancellation stops intermediate\n  branch states before expensive jobs fan out.\n- `make rust-checks` is the Rust-only local gate and should keep using\n  `--all-features`; the embedded UI feature is a normal CLI build surface.\n- The built UI artifact is produced by repo/CI orchestration (`make ui-build`\n  or the `UI build` workflow job), not by `crates/coral-cli/build.rs`. Local\n  Rust builds may compile without `apps/ui/dist`, because UI development normally\n  serves assets from Vite while the CLI provides the loopback API server.\n- Use `make docker-build` to compile the current checkout in a native Linux\n  BuildKit stage and package that binary as `coral:local`. Set\n  `DOCKER_IMAGE=coral:test` to change the local tag or `DOCKER_NO_CACHE=1` to\n  bypass Docker layer caching. Keep the exported-binary layout and runtime\n  platform aligned with the `docker-publish` workflow; local Docker-exporter\n  loads disable provenance because that exporter cannot load attestation\n  manifests. Local builds must not download a published Coral binary.\n- Use `make reef-docker-build` to build Reef from the current checkout and\n  `make reef-docker-smoke` to run the configuration matrix against an\n  already-built Reef image. Use the self-contained `make reef-docker-test` for\n  both. That matrix is peer-free: it asserts which runtime configurations boot\n  and which fail fast, while readiness against a live Coral is covered by the\n  mocked health client in `apps/reef/app/routes/readyz.server.test.ts`.\n- Use `make coral-docker-stub-test` to build the Coral image with a stub binary\n  and exercise `docker/entrypoint.sh` (config seeding, seed-once semantics, and\n  the unwritable-volume failure). The entrypoint is pure shell up to its closing\n  exec, so this needs no Rust build; the real binary is covered by\n  `make rust-checks` and the real image by the release smoke in\n  `.github/workflows/docker-publish.yml`. Reef's runtime stage must remain COPY-only and\n  non-root; build and dependency stages run on the build platform. Local builds\n  follow the Docker daemon's architecture, while CI builds and verifies\n  linux/amd64 only. TLS termination belongs to the operator and is\n  not provisioned by the image or its smoke harness.\n- Keep adapters thin. If CLI or MCP behavior gets complex, move it inward.\n- Keep server topology orchestration private to `coral-cli` while CLI commands\n  are its only consumers. Do not extract the orchestration into a shared\n  orchestration crate unless it gains a non-CLI consumer; the combined topology\n  is provisional and may be removed rather than promoted.\n- Keep transport contract concerns in `coral-api`, source-spec concerns in\n  `coral-spec`, app/state concerns in `coral-app`, and query/runtime\n  concerns in `coral-engine`.\n- Keep app-owned runtime package assembly in `coral-app`. `coral-engine`\n  should compile generic runtime components, not interpret DSL v4 authored\n  manifests, materialized fingerprints, semantic IR, or projection catalogs.\n- Keep Reef Coral access behind React Router server loaders, actions, or\n  resource routes using `apps/reef/app/lib/coral-request.server.ts`. Do not\n  expose a generic renderer-to-Coral transport or Desktop sidecar proxy; add an\n  explicit server route when browser-triggered Coral behavior is needed.\n- The packaged Reef server resolves its external runtime packages from the\n  Electron app. Keep every `apps/reef` production dependency represented in\n  `apps/desktop` production dependencies; the desktop config tests enforce this\n  packaging contract.\n- Use `CORAL_DESKTOP_APP=1` as Reef's single external desktop build marker.\n  React Router route composition may read it from `process.env`, while\n  `apps/reef/vite.config.ts` exposes only its compiled boolean value as\n  `import.meta.env.CORAL_DESKTOP_APP`. Do not add a parallel\n  `VITE_CORAL_DESKTOP_APP` marker or expose broader `CORAL_*` values to browser\n  code.\n- For DSL v4 materialization, the user owns when a source is generated or\n  regenerated. Coral materializes at source add, queries only from the\n  installed materialized package, and never silently refreshes descriptors,\n  projections, or persisted artifacts. Treat fingerprints, producer versions,\n  identity metadata, and raw-document hashes as advisory provenance: report\n  mismatches through tracing, but load readable, structurally compatible\n  artifacts. Isolate source-local compatibility failures without hiding\n  operational failures.\n- A DSL v4 source declares top-level `inputs:` and exactly one singular\n  `surface:`. The source `name` is its SQL namespace. Do not add surface ids,\n  namespace suffixes, or multiple surfaces to one manifest; represent distinct\n  provider interfaces as distinct source specs instead.\n- Keep cross-crate W3C trace-context propagation helpers in\n  `coral-telemetry`; do not make `coral-app`, `coral-client`, `coral-engine`,\n  or `coral-mcp` depend on each other just to share telemetry carrier logic.\n- Keep shared Arrow IPC decoding and result rendering in `coral-client`.\n- Treat `coral-app` as an internal composition root even if sibling crates use\n  its bootstrap seam today.\n- If a caller needs explicit local server control, prefer `coral-client::local`\n  over widening the default client surface.\n- Keep process environment access owned by the right crate. `coral-app` owns\n  runtime/bootstrap env reads, `coral-cli` owns CLI-surface env reads, and\n  other crates should receive explicit values from callers instead of reading\n  ambient process environment directly.\n- Keep docs lean and readable. For CLI or MCP changes, update `apps/docs/` only\n  when the change affects a public surface or captures important user-facing or\n  contributor-facing knowledge. Do not document every implementation detail.\n  When docs are warranted, choose the best existing location first and make the\n  amount of space match the feature's user-facing weight and visibility.\n- Keep stable bundled sources under `sources/core/**`; put preview DSL v4 source\n  specs under `sources/v4/[source]/manifest.yaml` with distinct manifest names\n  (defined in the manifest's `name` field) such as `<name>_v4`. When a provider\n  has distinct interfaces, use sibling source directories such as `github` and\n  `github_mcp`. Do not bundle\n  `sources/v4` into the binary; install preview v4 sources with\n  `coral source add --file`. Do not replace or migrate an existing v3 source\n  merely because a preview v4 spec exists.\n- Changes to `scripts/install.sh` must keep the `Validate` workflow's\n  install-script matrix in sync with every OS/architecture target that the\n  installer supports.\n- Keep general repository automation in `xtask`; reserve `scripts/` for the\n  bash Coral installer and installer-specific support.\n- Keep `xtask` organized by workflow: docs generation lives under\n  `xtask/src/docs/`, shared source-manifest discovery lives in\n  `xtask/src/sources.rs`, command-latency checks live in `xtask/src/perf.rs`,\n  benchmark dispatch lives under\n  `xtask/src/benchmarks/`, and the isolated benchmark package and fixtures live\n  under `xtask/benchmarks/`. Skill export lives in `xtask/src/skills.rs`.\n  Release signing and notarization automation lives in `xtask/src/release.rs`.\n  The DSL v4 inference report lives in `xtask/src/metadata_report.rs`.\n- Use `cargo run --locked -p xtask -- benchmark list-columns` to measure the\n  complete MCP `list_columns` response for the checked-in synthetic wide-table\n  fixture with the `o200k_base` tokenizer. The benchmark must call the real MCP\n  tool in-process, report without enforcing a token budget, and keep\n  benchmark-only code out of production crates.\n- Use `cargo run --locked -p xtask -- v4-metadata-report` before and after a\n  change to DSL v4 row-path, pagination, or lookup-key inference, and diff the\n  two reports. It imports every non-MCP v4 source under `sources/v4` and emits\n  one CSV row per operation, so an unintended reshape in a source nobody was\n  thinking about shows up as a diff hunk. Pass `--cache-dir` so a before/after pair fetches\n  each descriptor once. It is deliberately not wired into CI: it fetches\n  multi-megabyte vendor descriptors over the network, and vendor descriptors\n  change under us, so a green run proves nothing about the commit that produced\n  it.\n- Universal Search relevance benchmarking also lives in the isolated\n  `coral-benchmarks` package. Keep real catalog inventories, generated\n  questions, collected queries, responses, focused corpora, and replay reports\n  under ignored run directories. Only synthetic, deliberately non-sensitive\n  benchmark fixtures may be checked in. Use frozen-query replay rather than\n  rerunning agents while tuning ranking weights, and do not run agent\n  collection in CI.\n- The Electron desktop app version is tied to the CLI release version through\n  release-please. The release workflow builds the macOS desktop app from\n  `apps/desktop`, uploads its DMG/ZIP/update metadata to the same GitHub\n  Release as the CLI artifacts, and the website should link to the\n  `releases/latest/download` DMG rather than storing desktop binaries itself.\n- `make docs-check` intentionally skips the aggregate community source catalog.\n  Any PR may leave that generated page stale so unrelated changes do not fail\n  on aggregate community catalog drift; keep docs freshness strict for bundled\n  sources under `sources/core/**`, `apps/docs/docs.json`, and the changelog.\n- The live docs site deploys from the long-lived `docs` branch, not `main`, so\n  the published catalog matches the latest released binary. `main` still owns\n  docs freshness, but merging to `main` no longer publishes the site by itself:\n  the release workflow advances `docs` after release artifacts are published.\n  See `apps/docs/AGENTS.md` for the full publishing model.\n- Keep checked-in generated files marked in `.gitattributes` with\n  `linguist-generated` so GitHub collapses them by default in PR diffs.\n- Source inputs that carry credentials must be `kind: secret`, never\n  `kind: variable`. This includes API keys, bearer tokens, access tokens,\n  passwords, private keys, authorization header values, and admin/read keys,\n  even when the credential is read-only or the source also supports anonymous\n  access.\n- When source credential retrieval or auth guidance changes, keep the source\n  spec docs and maintained Coral source-spec skills aligned in the same change.\n  OAuth source-spec behavior needs both reader-facing docs and agent-facing\n  author/review guidance because `credential.methods` controls setup while\n  `auth` still controls runtime requests.\n- Keep maintained Coral agent skills in `plugins/coral/skills`. External\n  distribution repos or packages should mirror from that directory rather than\n  becoming a separate source of truth. Use\n  `cargo run --locked -p xtask -- export-skills --dest <path>` for local\n  export checks and distribution syncs.\n- Keep `plugins/coral` conformant with Agent Plugins 1.0: portable metadata\n  belongs in root `plugin.json`, skills are discovered from `skills/`, and MCP\n  servers are declared in root `mcp.json`. Keep the legacy `.codex-plugin`,\n  `.mcp.json`, and `.app.json` package files for pre-0.147 Codex compatibility.\n  Put current Codex-only metadata under `extensions.com.openai`, and align shared\n  metadata and MCP invocation across both representations.\n- Coral skills must include `agents/openai.yaml`. Keep\n  `interface.display_name` in the form `Coral` or `Coral <Title Case Suffix>`,\n  keep the top-level `SKILL.md` heading equal to that display name, and set\n  non-empty `short_description` and `default_prompt` values. The default prompt\n  should mention the skill token, such as `$coral-create-source-spec`.\n- When proposing or updating a PR title, use Conventional Commits:\n  `type(scope): summary`.\n- When using a scope, prefer one that matches the primary area changed,\n  usually the crate name minus the `coral-` prefix, `docs`,\n  `sources/core/<name>`, or `sources/community/<name>`.\n- Keep the PR title up to date as the branch evolves. If the change shifts in\n  scope or intent, update the title to match the current final shape of the\n  branch.\n- Use `!` only for breaking changes, placing it immediately before the colon:\n  `type!: summary` or `type(scope)!: summary`. Local WIP commit messages can\n  stay pragmatic unless the user explicitly asks for polished commit history.\n- If you add a source using dummy credentials in order to test a change, always\n  configure Coral to store those credentials on the filesystem. Do not store\n  dummy credentials in the OS keychain.\n\n## Meta Changes\n\nA meta change modifies how contributors or agents should work in this repo, not\nonly runtime behavior. Examples include repo layout, crate ownership, source\ndirectory conventions, docs generation behavior, CLI/MCP surface rules, PR\ntitle/scope guidance, verification commands, and agent-facing review or\nsource-authoring instructions.\n\nFor meta changes:\n\n- Update the nearest relevant `AGENTS.md` in the same change.\n- Update `apps/docs/`, generated docs, or docs tooling only when the changed\n  behavior is user-facing or docs-authoring-facing, and use the smallest useful\n  edit in the best existing location.\n- Preserve provenance: keep observed repo facts, project direction, local\n  preferences, and generated context separate instead of merging them into one\n  untraceable rule.\n- Treat repeated human steering as a defect in the operating loop. Identify the\n  failure class, update durable context or tooling when that can prevent\n  recurrence, and verify the new rule before resuming unrelated work.\n- Include explicit validation showing the guidance matches the implemented\n  behavior.\n- Mention in the PR description what agent or contributor behavior changed.\n\n## What Counts As a Breaking Change for a CLI?\n\nFor a CLI, the user interface is the API.\n\nA change is breaking if it can break existing:\n\n- commands people run manually\n- scripts and CI jobs\n- documented workflows\n- integrations that parse output\n\nTreat these as stable contract surfaces:\n\n- command/subcommand names\n- flags and positional arguments\n- exit codes\n- structured output (for example JSON)\n- config file keys, format, and location\n- environment variables and precedence rules\n\nIf any of those change incompatibly, it is a breaking change.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Repo Map\n\n- `crates/coral-api`: protobuf contract and generated Rust bindings.\n- `crates/coral-app`: local server composition, state, workspaces, source\n  lifecycle, and workspace-scoped catalog discovery behavior.\n- `crates/coral-cli`: terminal adapter.\n- `crates/coral-client`: intentionally thin transport bootstrap plus\n  Arrow IPC decode/render helpers.\n- `crates/coral-engine`: engine-side backend compilation, runtime registration,\n  and query execution.\n- `crates/coral-mcp`: MCP tool core with stdio and Streamable HTTP transport\n  adapters over `coral-client`.\n- `crates/coral-spec`: declarative source-spec parsing, validation,\n  input discovery, and normalized source-definition models.\n- `crates/coral-telemetry`: cross-crate telemetry helpers that are independent\n  of app bootstrap, query runtime, and adapter surfaces.\n- `apps/desktop`: Electron shell around Reef and the local Coral sidecar.\n- `apps/docs`: Mintlify documentation site.\n- `apps/reef`: React Router/Wax frontend shell. It is validated independently\n  from `apps/ui` and is not built by Rust crate build scripts.\n- `apps/ui`: embedded Coral app UI built into the CLI release flow.\n- `plugins/coral`: Agent plugin packaging. `plugins/coral/skills` is the\n  canonical in-repo home for maintained Coral agent skills.\n\n## Rules\n\n- Run `make rust-checks` before submitting PRs that include changes to Rust code.\n- For Postgres-backed database changes, run `make postgres-tests`. Keep this as\n  the single entry point for local and CI Postgres coverage; do not duplicate\n  its Cargo test invocations in workflows or contributor instructions. The\n  target uses `CORAL_TEST_POSTGRES_URL` when supplied. Otherwise it starts a\n  local Docker Postgres and creates a fresh database inside the reusable\n  container. Docker chooses an available localhost port by default; use\n  `make postgres-url` to print the server URL or\n  `LOCAL_POSTGRES_PORT=55432 make postgres-start` when you need a stable port.\n  Use `make postgres-start` when you only need the server,\n  `make postgres-stop` when finished, and `make postgres-clean` to remove the\n  reusable container.\n- Run `make schema-check` before submitting PRs that touch generated manifest\n  schemas or the Rust helpers that generate them. Use\n  `make schema-generate` to refresh generated schema files. The Validate\n  workflow enforces this through its `schema-freshness` job when schema inputs\n  change.\n- UI changes must pass `npm run check --prefix apps/ui` (oxfmt + oxlint) before submitting.\n- Reef changes must pass `npm run check --prefix apps/reef`,\n  `npm run typecheck --prefix apps/reef`, `npm test --prefix apps/reef`, and\n  `npm run build --prefix apps/reef`, followed by\n  `npm run test:server --prefix apps/reef`, before submitting. The production\n  server smoke test consumes the build output and runs on every Reef CI job.\n- Desktop changes must pass `npm run check --prefix apps/desktop` and\n  `npm test --prefix apps/desktop` before submitting.\n- Keep Reef Vitest coverage Node-only and focused on atomic deterministic\n  functions and policies or explicit architectural invariants. Do not add broad\n  browser, router, or framework-plumbing tests without a named contract or\n  regression they protect.\n- Use Storybook and Chromatic for Reef component visual states.\n- Reef styling uses vanilla-extract; do not introduce Tailwind.\n- Run `make perf-check` before submitting PRs that could affect CLI startup,\n  local server bootstrap, source registration, or `coral.tables` catalog query\n  latency. CI installs the bundled `github` source with fake credentials and\n  fails when release `coral sql \"select * from coral.tables\"` has a hyperfine\n  mean above 750 ms.\n- Pull requests do not automatically build macOS Desktop packages. Use manual\n  dispatch for an unsigned packaging preflight when a distribution-sensitive\n  change warrants one. Validation artifacts stay unsigned and must not be\n  reused for a release; Desktop release publishing must rebuild from a clean\n  checkout with signing and notarization.\n- The `Validate` workflow intentionally skips draft pull request runs, starts\n  again on `ready_for_review`, and still triggers on `converted_to_draft` so the\n  replacement skipped run cancels any in-progress validation for the PR branch.\n  Keep that draft gate aligned between the initial change detector and final\n  aggregate `validate` job.\n- Keep Release Please branch updates coalesced and cheap to supersede. The\n  `release-please` workflow may create multiple local regeneration commits, but\n  must push them together through its final push step. `Validate` intentionally\n  gives `release-please--*` pull requests a 120-second settle period before\n  checkout and change detection so concurrency cancellation stops intermediate\n  branch states before expensive jobs fan out.\n- `make rust-checks` is the Rust-only local gate and should keep using\n  `--all-features`; the embedded UI feature is a normal CLI build surface.\n- The built UI artifact is produced by repo/CI orchestration (`make ui-build`\n  or the `UI build` workflow job), not by `crates/coral-cli/build.rs`. Local\n  Rust builds may compile without `apps/ui/dist`, because UI development normally\n  serves assets from Vite while the CLI provides the loopback API server.\n- Use `make docker-build` to compile the current checkout in a native Linux\n  BuildKit stage and package that binary as `coral:local`. Set\n  `DOCKER_IMAGE=coral:test` to change the local tag or `DOCKER_NO_CACHE=1` to\n  bypass Docker layer caching. Keep the exported-binary layout and runtime\n  platform aligned with the `docker-publish` workflow; local Docker-exporter\n  loads disable provenance because that exporter cannot load attestation\n  manifests. Local builds must not download a published Coral binary.\n- Use `make reef-docker-build` to build Reef from the current checkout and\n  `make reef-docker-smoke` to run the configuration matrix against an\n  already-built Reef image. Use the self-contained `make reef-docker-test` for\n  both. That matrix is peer-free: it asserts which runtime configurations boot\n  and which fail fast, while readiness against a live Coral is covered by the\n  mocked health client in `apps/reef/app/routes/readyz.server.test.ts`.\n- Use `make coral-docker-stub-test` to build the Coral image with a stub binary\n  and exercise `docker/entrypoint.sh` (config seeding, seed-once semantics, and\n  the unwritable-volume failure). The entrypoint is pure shell up to its closing\n  exec, so this needs no Rust build; the real binary is covered by\n  `make rust-checks` and the real image by the release smoke in\n  `.github/workflows/docker-publish.yml`. Reef's runtime stage must remain COPY-only and\n  non-root; build and dependency stages run on the build platform. Local builds\n  follow the Docker daemon's architecture, while CI builds and verifies\n  linux/amd64 only. TLS termination belongs to the operator and is\n  not provisioned by the image or its smoke harness.\n- Keep adapters thin. If CLI or MCP behavior gets complex, move it inward.\n- Keep server topology orchestration private to `coral-cli` while CLI commands\n  are its only consumers. Do not extract the orchestration into a shared\n  orchestration crate unless it gains a non-CLI consumer; the combined topology\n  is provisional and may be removed rather than promoted.\n- Keep transport contract concerns in `coral-api`, source-spec concerns in\n  `coral-spec`, app/state concerns in `coral-app`, and query/runtime\n  concerns in `coral-engine`.\n- Keep app-owned runtime package assembly in `coral-app`. `coral-engine`\n  should compile generic runtime components, not interpret DSL v4 authored\n  manifests, materialized fingerprints, semantic IR, or projection catalogs.\n- Keep Reef Coral access behind React Router server loaders, actions, or\n  resource routes using `apps/reef/app/lib/coral-request.server.ts`. Do not\n  expose a generic renderer-to-Coral transport or Desktop sidecar proxy; add an\n  explicit server route when browser-triggered Coral behavior is needed.\n- The packaged Reef server resolves its external runtime packages from the\n  Electron app. Keep every `apps/reef` production dependency represented in\n  `apps/desktop` production dependencies; the desktop config tests enforce this\n  packaging contract.\n- Use `CORAL_DESKTOP_APP=1` as Reef's single external desktop build marker.\n  React Router route composition may read it from `process.env`, while\n  `apps/reef/vite.config.ts` exposes only its compiled boolean value as\n  `import.meta.env.CORAL_DESKTOP_APP`. Do not add a parallel\n  `VITE_CORAL_DESKTOP_APP` marker or expose broader `CORAL_*` values to browser\n  code.\n- For DSL v4 materialization, the user owns when a source is generated or\n  regenerated. Coral materializes at source add, queries only from the\n  installed materialized package, and never silently refreshes descriptors,\n  projections, or persisted artifacts. Treat fingerprints, producer versions,\n  identity metadata, and raw-document hashes as advisory provenance: report\n  mismatches through tracing, but load readable, structurally compatible\n  artifacts. Isolate source-local compatibility failures without hiding\n  operational failures.\n- A DSL v4 source declares top-level `inputs:` and exactly one singular\n  `surface:`. The source `name` is its SQL namespace. Do not add surface ids,\n  namespace suffixes, or multiple surfaces to one manifest; represent distinct\n  provider interfaces as distinct source specs instead.\n- Keep cross-crate W3C trace-context propagation helpers in\n  `coral-telemetry`; do not make `coral-app`, `coral-client`, `coral-engine`,\n  or `coral-mcp` depend on each other just to share telemetry carrier logic.\n- Keep shared Arrow IPC decoding and result rendering in `coral-client`.\n- Treat `coral-app` as an internal composition root even if sibling crates use\n  its bootstrap seam today.\n- If a caller needs explicit local server control, prefer `coral-client::local`\n  over widening the default client surface.\n- Keep process environment access owned by the right crate. `coral-app` owns\n  runtime/bootstrap env reads, `coral-cli` owns CLI-surface env reads, and\n  other crates should receive explicit values from callers instead of reading\n  ambient process environment directly.\n- Keep docs lean and readable. For CLI or MCP changes, update `apps/docs/` only\n  when the change affects a public surface or captures important user-facing or\n  contributor-facing knowledge. Do not document every implementation detail.\n  When docs are warranted, choose the best existing location first and make the\n  amount of space match the feature's user-facing weight and visibility.\n- Keep stable bundled sources under `sources/core/**`; put preview DSL v4 source\n  specs under `sources/v4/[source]/manifest.yaml` with distinct manifest names\n  (defined in the manifest's `name` field) such as `<name>_v4`. When a provider\n  has distinct interfaces, use sibling source directories such as `github` and\n  `github_mcp`. Do not bundle\n  `sources/v4` into the binary; install preview v4 sources with\n  `coral source add --file`. Do not replace or migrate an existing v3 source\n  merely because a preview v4 spec exists.\n- Changes to `scripts/install.sh` must keep the `Validate` workflow's\n  install-script matrix in sync with every OS/architecture target that the\n  installer supports.\n- Keep general repository automation in `xtask`; reserve `scripts/` for the\n  bash Coral installer and installer-specific support.\n- Keep `xtask` organized by workflow: docs generation lives under\n  `xtask/src/docs/`, shared source-manifest discovery lives in\n  `xtask/src/sources.rs`, command-latency checks live in `xtask/src/perf.rs`,\n  benchmark dispatch lives under\n  `xtask/src/benchmarks/`, and the isolated benchmark package and fixtures live\n  under `xtask/benchmarks/`. Skill export lives in `xtask/src/skills.rs`.\n  Release signing and notarization automation lives in `xtask/src/release.rs`.\n  The DSL v4 inference report lives in `xtask/src/metadata_report.rs`.\n- Use `cargo run --locked -p xtask -- benchmark list-columns` to measure the\n  complete MCP `list_columns` response for the checked-in synthetic wide-table\n  fixture with the `o200k_base` tokenizer. The benchmark must call the real MCP\n  tool in-process, report without enforcing a token budget, and keep\n  benchmark-only code out of production crates.\n- Use `cargo run --locked -p xtask -- v4-metadata-report` before and after a\n  change to DSL v4 row-path, pagination, or lookup-key inference, and diff the\n  two reports. It imports every non-MCP v4 source under `sources/v4` and emits\n  one CSV row per operation, so an unintended reshape in a source nobody was\n  thinking about shows up as a diff hunk. Pass `--cache-dir` so a before/after pair fetches\n  each descriptor once. It is deliberately not wired into CI: it fetches\n  multi-megabyte vendor descriptors over the network, and vendor descriptors\n  change under us, so a green run proves nothing about the commit that produced\n  it.\n- Universal Search relevance benchmarking also lives in the isolated\n  `coral-benchmarks` package. Keep real catalog inventories, generated\n  questions, collected queries, responses, focused corpora, and replay reports\n  under ignored run directories. Only synthetic, deliberately non-sensitive\n  benchmark fixtures may be checked in. Use frozen-query replay rather than\n  rerunning agents while tuning ranking weights, and do not run agent\n  collection in CI.\n- The Electron desktop app version is tied to the CLI release version through\n  release-please. The release workflow builds the macOS desktop app from\n  `apps/desktop`, uploads its DMG/ZIP/update metadata to the same GitHub\n  Release as the CLI artifacts, and the website should link to the\n  `releases/latest/download` DMG rather than storing desktop binaries itself.\n- `make docs-check` intentionally skips the aggregate community source catalog.\n  Any PR may leave that generated page stale so unrelated changes do not fail\n  on aggregate community catalog drift; keep docs freshness strict for bundled\n  sources under `sources/core/**`, `apps/docs/docs.json`, and the changelog.\n- The live docs site deploys from the long-lived `docs` branch, not `main`, so\n  the published catalog matches the latest released binary. `main` still owns\n  docs freshness, but merging to `main` no longer publishes the site by itself:\n  the release workflow advances `docs` after release artifacts are published.\n  See `apps/docs/AGENTS.md` for the full publishing model.\n- Keep checked-in generated files marked in `.gitattributes` with\n  `linguist-generated` so GitHub collapses them by default in PR diffs.\n- Source inputs that carry credentials must be `kind: secret`, never\n  `kind: variable`. This includes API keys, bearer tokens, access tokens,\n  passwords, private keys, authorization header values, and admin/read keys,\n  even when the credential is read-only or the source also supports anonymous\n  access.\n- When source credential retrieval or auth guidance changes, keep the source\n  spec docs and maintained Coral source-spec skills aligned in the same change.\n  OAuth source-spec behavior needs both reader-facing docs and agent-facing\n  author/review guidance because `credential.methods` controls setup while\n  `auth` still controls runtime requests.\n- Keep maintained Coral agent skills in `plugins/coral/skills`. External\n  distribution repos or packages should mirror from that directory rather than\n  becoming a separate source of truth. Use\n  `cargo run --locked -p xtask -- export-skills --dest <path>` for local\n  export checks and distribution syncs.\n- Keep `plugins/coral` conformant with Agent Plugins 1.0: portable metadata\n  belongs in root `plugin.json`, skills are discovered from `skills/`, and MCP\n  servers are declared in root `mcp.json`. Keep the legacy `.codex-plugin`,\n  `.mcp.json`, and `.app.json` package files for pre-0.147 Codex compatibility.\n  Put current Codex-only metadata under `extensions.com.openai`, and align shared\n  metadata and MCP invocation across both representations.\n- Coral skills must include `agents/openai.yaml`. Keep\n  `interface.display_name` in the form `Coral` or `Coral <Title Case Suffix>`,\n  keep the top-level `SKILL.md` heading equal to that display name, and set\n  non-empty `short_description` and `default_prompt` values. The default prompt\n  should mention the skill token, such as `$coral-create-source-spec`.\n- When proposing or updating a PR title, use Conventional Commits:\n  `type(scope): summary`.\n- When using a scope, prefer one that matches the primary area changed,\n  usually the crate name minus the `coral-` prefix, `docs`,\n  `sources/core/<name>`, or `sources/community/<name>`.\n- Keep the PR title up to date as the branch evolves. If the change shifts in\n  scope or intent, update the title to match the current final shape of the\n  branch.\n- Use `!` only for breaking changes, placing it immediately before the colon:\n  `type!: summary` or `type(scope)!: summary`. Local WIP commit messages can\n  stay pragmatic unless the user explicitly asks for polished commit history.\n- If you add a source using dummy credentials in order to test a change, always\n  configure Coral to store those credentials on the filesystem. Do not store\n  dummy credentials in the OS keychain.\n\n## Meta Changes\n\nA meta change modifies how contributors or agents should work in this repo, not\nonly runtime behavior. Examples include repo layout, crate ownership, source\ndirectory conventions, docs generation behavior, CLI/MCP surface rules, PR\ntitle/scope guidance, verification commands, and agent-facing review or\nsource-authoring instructions.\n\nFor meta changes:\n\n- Update the nearest relevant `AGENTS.md` in the same change.\n- Update `apps/docs/`, generated docs, or docs tooling only when the changed\n  behavior is user-facing or docs-authoring-facing, and use the smallest useful\n  edit in the best existing location.\n- Preserve provenance: keep observed repo facts, project direction, local\n  preferences, and generated context separate instead of merging them into one\n  untraceable rule.\n- Treat repeated human steering as a defect in the operating loop. Identify the\n  failure class, update durable context or tooling when that can prevent\n  recurrence, and verify the new rule before resuming unrelated work.\n- Include explicit validation showing the guidance matches the implemented\n  behavior.\n- Mention in the PR description what agent or contributor behavior changed.\n\n## What Counts As a Breaking Change for a CLI?\n\nFor a CLI, the user interface is the API.\n\nA change is breaking if it can break existing:\n\n- commands people run manually\n- scripts and CI jobs\n- documented workflows\n- integrations that parse output\n\nTreat these as stable contract surfaces:\n\n- command/subcommand names\n- flags and positional arguments\n- exit codes\n- structured output (for example JSON)\n- config file keys, format, and location\n- environment variables and precedence rules\n\nIf any of those change incompatibly, it is a breaking change.\n","category":"root","tokens":4779}]}