","directories":{},"_nodeVersion":"24.18.0","dependencies":{"yaml":"^2.3.4","express":"^4.22.1","commander":"^14.0.3","openapi-types":"^12.1.3","isomorphic-git":"^1.37.6","@asyncapi/parser":"^3.6.0","@toon-format/toon":"^2.1.0","@modelcontextprotocol/sdk":"^1.0.0","@apidevtools/swagger-parser":"^12.1.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^24.0.0","@types/express":"^4.17.25","@types/swagger-parser":"^4.0.3"},"_npmOperationalInternal":{"tmp":"tmp/corum_0.1.49_1784762761879_0.14989106517582296","host":"s3://npm-registry-packages-npm-production"}},"0.1.50":{"name":"@atolis-hq/corum","version":"0.1.50","_id":"@atolis-hq/corum@0.1.50","maintainers":[{"name":"jmenziessmith","email":"jon@menzies-smith.co.uk"}],"homepage":"https://github.com/atolis-hq/corum#readme","bugs":{"url":"https://github.com/atolis-hq/corum/issues"},"bin":{"corum":"dist/src/bin/corum.js"},"dist":{"shasum":"f1aae60fe69285cf3a0c07f0b6d25050f5b8157f","tarball":"https://registry.npmjs.org/@atolis-hq/corum/-/corum-0.1.50.tgz","fileCount":76,"integrity":"sha512-LVRG5ova2PClQ/FkZTzCu4HW7+c3yujL0/1juLOQtGN2+sz4lIlVqaZ5hwHhn8SJmdQw8Y3aPxThId1et2WCdA==","signatures":[{"sig":"MEUCIGRYeJJylOUnCcSxsEk8bbnRAZG72DHC0Ts4OqIgNZhVAiEA9P3URpOhSr70/D5qyPxELMOYpSpfSMM+gIW0dPjDUd4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@atolis-hq%2fcorum@0.1.50","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":646097},"type":"module","gitHead":"1b62360e2fa008430345a8dcebdeae4d01d1136d","scripts":{"mcp":"node dist/src/mcp/index.js","web":"node dist/src/web/server.js","test":"tsc && node scripts/run-tests.mjs","build":"tsc","mcp:smoke":"npm run build && node scripts/mcp-smoke.mjs","wireframes":"node design/wireframes/server.mjs","mcp:write-smoke":"npm run build && node scripts/mcp-write-smoke.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cdb81a4c-5f79-45bc-94fd-6e2056a60f27"}},"repository":{"url":"git+https://github.com/atolis-hq/corum.git","type":"git"},"_npmVersion":"11.16.0","description":"
","directories":{},"_nodeVersion":"24.18.0","dependencies":{"yaml":"^2.3.4","express":"^4.22.1","commander":"^14.0.3","openapi-types":"^12.1.3","isomorphic-git":"^1.37.6","@asyncapi/parser":"^3.6.0","@toon-format/toon":"^2.1.0","@modelcontextprotocol/sdk":"^1.0.0","@apidevtools/swagger-parser":"^12.1.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^24.0.0","@types/express":"^4.17.25","@types/swagger-parser":"^4.0.3"},"_npmOperationalInternal":{"tmp":"tmp/corum_0.1.50_1786441012676_0.8357818946671292","host":"s3://npm-registry-packages-npm-production"}},"0.1.51":{"name":"@atolis-hq/corum","version":"0.1.51","type":"module","repository":{"type":"git","url":"git+https://github.com/atolis-hq/corum.git"},"bin":{"corum":"dist/src/bin/corum.js"},"scripts":{"build":"tsc","test":"tsc && node scripts/run-tests.mjs","wireframes":"node design/wireframes/server.mjs","mcp":"node dist/src/mcp/index.js","mcp:smoke":"npm run build && node scripts/mcp-smoke.mjs","mcp:write-smoke":"npm run build && node scripts/mcp-write-smoke.mjs","web":"node dist/src/web/server.js"},"dependencies":{"@apidevtools/swagger-parser":"^12.1.0","@asyncapi/parser":"^3.6.0","@modelcontextprotocol/sdk":"^1.0.0","@toon-format/toon":"^2.1.0","commander":"^14.0.3","express":"^4.22.1","isomorphic-git":"^1.37.6","openapi-types":"^12.1.3","yaml":"^2.3.4"},"devDependencies":{"@types/express":"^4.17.25","@types/node":"^24.0.0","@types/swagger-parser":"^4.0.3","typescript":"^5.0.0"},"gitHead":"751d00e09fc05c4b65577d6eda616024009fed4e","_id":"@atolis-hq/corum@0.1.51","description":"
","bugs":{"url":"https://github.com/atolis-hq/corum/issues"},"homepage":"https://github.com/atolis-hq/corum#readme","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-R4Zm+Yo/GHNFD4rl6n9uKCqw3Vrtbk6pheofHo5+YwGjxigegzRwpN93454lAkEzn++o19MgrsoccQ9b7qxAPA==","shasum":"f48634ab540ed25ee5eaa56e6f25af6c361e8cac","tarball":"https://registry.npmjs.org/@atolis-hq/corum/-/corum-0.1.51.tgz","fileCount":76,"unpackedSize":646636,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@atolis-hq%2fcorum@0.1.51","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDrQ1tOryX4cnmjqQSMCLZ0gru+7xBVdrkxVxTxlc0SVgIhAK0ezI8O5IwxK9hviTjQMUrVfaHdpYgRatLbuKquw3wO"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cdb81a4c-5f79-45bc-94fd-6e2056a60f27"}},"directories":{},"maintainers":[{"name":"jmenziessmith","email":"jon@menzies-smith.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/corum_0.1.51_1786442430872_0.6867149131182908"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-18T19:12:08.474Z","modified":"2026-08-11T10:00:31.430Z","0.1.0":"2026-06-18T19:12:08.754Z","0.1.5":"2026-06-18T20:39:50.864Z","0.1.6":"2026-06-18T20:57:18.793Z","0.1.7":"2026-06-18T22:20:33.576Z","0.1.8":"2026-06-18T22:29:00.094Z","0.1.9":"2026-06-18T22:36:48.728Z","0.1.10":"2026-06-18T22:59:09.889Z","0.1.11":"2026-06-18T23:24:46.176Z","0.1.12":"2026-06-19T08:07:59.725Z","0.1.13":"2026-06-19T18:35:07.263Z","0.1.14":"2026-06-19T19:32:06.339Z","0.1.15":"2026-06-19T20:54:09.799Z","0.1.16":"2026-06-19T21:20:57.607Z","0.1.17":"2026-06-19T23:15:26.117Z","0.1.18":"2026-06-23T00:12:15.971Z","0.1.19":"2026-06-23T11:33:57.918Z","0.1.20":"2026-06-25T11:29:41.772Z","0.1.21":"2026-06-25T14:00:49.529Z","0.1.22":"2026-06-25T20:14:42.252Z","0.1.23":"2026-06-29T22:27:32.594Z","0.1.24":"2026-06-30T08:26:04.476Z","0.1.25":"2026-06-30T09:13:06.796Z","0.1.26":"2026-06-30T12:52:52.559Z","0.1.27":"2026-06-30T17:37:29.151Z","0.1.28":"2026-06-30T20:26:38.743Z","0.1.29":"2026-06-30T22:45:38.302Z","0.1.30":"2026-06-30T23:01:56.446Z","0.1.31":"2026-07-01T08:16:45.832Z","0.1.32":"2026-07-01T08:36:18.345Z","0.1.33":"2026-07-01T12:18:24.916Z","0.1.34":"2026-07-01T14:42:30.853Z","0.1.35":"2026-07-01T17:35:19.621Z","0.1.36":"2026-07-01T18:22:28.777Z","0.1.37":"2026-07-01T18:56:35.503Z","0.1.38":"2026-07-01T20:31:18.399Z","0.1.39":"2026-07-01T23:57:17.044Z","0.1.40":"2026-07-03T13:34:54.528Z","0.1.41":"2026-07-03T16:37:34.942Z","0.1.42":"2026-07-03T18:54:18.381Z","0.1.43":"2026-07-03T19:58:37.369Z","0.1.44":"2026-07-04T00:12:11.179Z","0.1.45":"2026-07-04T23:19:27.824Z","0.1.46":"2026-07-05T08:02:43.237Z","0.1.47":"2026-07-22T23:14:23.414Z","0.1.48":"2026-07-22T23:22:50.803Z","0.1.49":"2026-07-22T23:26:02.046Z","0.1.50":"2026-08-11T09:36:52.906Z","0.1.51":"2026-08-11T10:00:31.065Z"},"bugs":{"url":"https://github.com/atolis-hq/corum/issues"},"homepage":"https://github.com/atolis-hq/corum#readme","repository":{"type":"git","url":"git+https://github.com/atolis-hq/corum.git"},"description":"
","maintainers":[{"name":"jmenziessmith","email":"jon@menzies-smith.co.uk"}],"readme":"
\n\n\n
![\"logo\"](\"https://raw.githubusercontent.com/atolis-hq/corum/refs/heads/main/assets/corum-logo.svg\")
\n
Corum
\n \n
\n Unified system design surface, built for agents and humans.\n
\n \n \n\n
\n \n ![\"last](\"https://img.shields.io/github/last-commit/atolis-hq/corum\")
\n \n \n ![\"CI/CD](\"https://github.com/atolis-hq/corum/actions/workflows/ci-cd.yml/badge.svg\")
\n \n \n \n ![\"open](\"https://img.shields.io/github/issues/atolis-hq/corum\")
\n \n \n ![\"license\"](\"https://img.shields.io/github/license/atolis-hq/corum.svg\")
\n \n \n ![\"latest](\"https://img.shields.io/github/v/tag/atolis-hq/corum\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/v/%40atolis-hq%2Fcorum\")
\n \n
\n
\n\n
\n\n\nCorum is a Git-native, extensible design graph for software architecture. It models components as nodes with typed edges, and exposes the graph through MCP tools so AI assistants can reason about and evolve your architecture. Corum provides several out of the box schemas (such as APIs, domain models, events, schemas, fields) but can be customised to model any data structure. The graph enables modelling data lineage at object and field level, and the branching model enables multiple simultaneous designs with cross branch impact analysis.\n\n## Install\n\n```bash\nnpm install -g @atolis-hq/corum\n```\n\nOr run without installing:\n\n```bash\nnpx @atolis-hq/corum
\n```\n\n**Windows:** If you see an \"execution policy\" error in PowerShell, run this once:\n\n```powershell\nSet-ExecutionPolicy RemoteSigned -Scope CurrentUser\n```\n\nThis is a standard one-time setup step for Node.js development on Windows. Alternatively, `npx @atolis-hq/corum ` works without any setup on all platforms.\n\n## Update\n\n```bash\nnpm update -g @atolis-hq/corum\n```\n\n## Quick Start\n\nScaffold a new project in the current directory:\n\n```bash\ncorum init\n```\n\nThis creates `.corum/config.yaml`, scaffolds a graph at `.corum/graph/`, and downloads the official template packs (`core`, `domain`, `rest`, `messaging`). Then start the MCP server:\n\n```bash\ncorum mcp\n```\n\nIf you only want the web UI:\n\n```bash\ncorum web\n```\n\n## Commands\n\n### `corum mcp`\n\nStart the MCP stdio server. Also starts a web UI by default.\n\n```bash\ncorum mcp [options]\n\nOptions:\n --no-web Suppress the web UI\n --watch Reload file-backed graphs on local file changes\n --graph Override the graph directory\n```\n\nNotes:\n- `corum mcp` starts the web UI unless you pass `--no-web`.\n- `--watch` applies to filesystem graphs. Git-backed graphs reload through polling instead.\n\n### `corum web`\n\nStart the web UI only.\n\n```bash\ncorum web [options]\n\nOptions:\n --port Port to listen on (default: 3000)\n --graph Override the graph directory\n```\n\nNotes:\n- Filesystem graphs can be watched for local YAML changes with `CORUM_FILE_WATCHER=true` or `CORUM_WATCH=true`.\n- Git-backed graphs reload through polling when `git_poll_seconds` / `CORUM_GIT_POLL_SECONDS` is set.\n\n### `corum lint`\n\nLint the graph and report diagnostics.\n\n```bash\ncorum lint [options]\n\nOptions:\n --graph Override the graph directory\n```\n\n### `corum init`\n\nScaffold a `.corum/` project structure and install the four default template packs (`core`, `domain`, `rest`, `messaging`). Skips any step where the target already exists.\n\n```bash\ncorum init\n```\n\nCreates:\n- `.corum/config.yaml` - project configuration\n- `.corum/graph/graph.yaml` - graph definition\n- `.corum/graph/components/` and `.corum/graph/edges/` - empty directories ready for nodes\n- `.corum/packs/` - downloaded template packs\n- `.corum/packs.yaml` - local manifest of installed packs\n\n### `corum pack install`\n\nInstall a template pack from the registry into `.corum/packs/`. Appends the pack to `.corum/graph/graph.yaml` and records it in `.corum/packs.yaml`.\n\n```bash\ncorum pack install # install latest tag\ncorum pack install @[ # install a specific tag\n```\n\nExamples:\n\n```bash\ncorum pack install domain\ncorum pack install domain@v0.1.5\ncorum pack install extract # required for corum-extract import adapter\n```\n\n### `corum pack list`\n\nList installed packs with their resolved version and install date.\n\n```bash\ncorum pack list\n```\n\n### `corum import`\n\nImport specifications into the graph.\n\n```bash\ncorum import --config Import using a config YAML file\n```\n\n#### Import config file\n\nThe `--config` flag accepts a YAML file that can combine multiple imports in a single run and configure cross-adapter options:\n\n```yaml\n# Optional: remap extracted component names before node IDs are built.\n# Useful when the same component appears under different names in different specs\n# (e.g. \"order-shipping\" from a URI segment vs \"ordershipping\" from a topic name).\ncomponentNameReplacements:\n - from: ordershipping\n to: order-shipping\n\n# Optional: deduplicate nodes emitted by different adapters after all imports\n# complete. For each rule, keep nodes from the primary adapter and merge/drop\n# matching nodes from the secondary adapter.\ndeduplication:\n - primary: openapi\n secondary: corum\n\nimports:\n - adapter: openapi\n spec: ./specs/order-shipping.openapi.yaml\n componentMapping:\n strategy: uri-segment\n segment: 0\n\n - adapter: asyncapi\n spec: ./specs/order-shipping.asyncapi.yaml\n componentMapping:\n strategy: channel-segment\n separator: \".\"\n segment: 0\n messageNaming:\n strategy: name-segment\n separator: \".\"\n segment: -1\n```\n\nReplacements are applied in order; the first matching `from` wins. Unmatched names are passed through unchanged.\nDeduplication rules are applied after all adapters finish. They are intended for\ncross-adapter reconciliation, for example keeping OpenAPI endpoints as canonical\nwhile merging matching extractor-emitted Corum nodes into them.\n\n#### `corum import openapi `\n\nImport an OpenAPI spec directly.\n\n```bash\ncorum import openapi [options]\n\nOptions:\n --component-strategy Component mapping: uri-segment (default), tag, hardcoded\n --segment URI segment index (uri-segment strategy)\n --pattern Regex pattern (uri-segment strategy)\n --component Component name (hardcoded strategy)\n --graph Override the graph directory\n```\n\n#### `corum import asyncapi `\n\nImport an AsyncAPI spec directly.\n\n```bash\ncorum import asyncapi [options]\n\nOptions:\n --component-strategy Component mapping: channel-segment (default), channel-pattern,\n name-segment, name-pattern, tag, hardcoded\n --separator Separator for segment strategies (default: .)\n --segment Segment index (negative counts from end)\n --pattern Regex pattern for pattern strategies\n --component Component name (hardcoded strategy)\n --event-classification always-integration (default) or always-domain\n --include-consumed Also import receive (consumed) operations\n --graph Override the graph directory\n```\n\n#### `corum import corum `\n\nImport a corum interchange file (`*.corum.yaml`) produced by `corum-extract` or compatible extraction tooling.\n\n```bash\ncorum import corum [options]\n\nOptions:\n --graph Override the graph directory\n```\n\nThe interchange format is self-describing - no component mapping strategy is needed. Node IDs, template names, and field references are already corum-native. Gaps reported by the extractor (unresolved types, name collisions) are surfaced as warnings.\n\nRequires the `extract` pack to be active in your graph:\n\n```bash\ncorum pack install extract\n```\n\nYou can also configure corum imports in a config file:\n\n```yaml\n# .corum/imports.yaml\nimports:\n - adapter: corum\n spec: path/to/output.corum.yaml\n```\n\n## Configuration\n\nRun `corum init` to generate a `.corum/config.yaml` with all available options. Corum walks up from the current directory to find it, so you can place it at your project root.\n\n**Precedence (highest to lowest):** CLI flags -> environment variables -> `.corum/config.yaml`\n\n| Config key | Environment variable | Description |\n|---|---|---|\n| `pack_registry` | - | URL of the pack registry YAML (set by `corum init`) |\n| `source` | `CORUM_SOURCE` | Source mode: `file` / `filesystem` / `fs` (default) or `git` |\n| `graph` | `CORUM_GRAPH_PATH` | Path to the graph directory |\n| `git_local_path` | `CORUM_GIT_LOCAL_PATH` | Local git repo path |\n| `git_remote_url` | `CORUM_GIT_REMOTE_URL` | Remote git repo URL |\n| `git_branch` | `CORUM_GIT_BRANCH` | Default branch ref used when loading a git-backed graph |\n| `git_poll_seconds` | `CORUM_GIT_POLL_SECONDS` | Poll interval, in seconds, for git-backed web reloads |\n| `git_token` | `CORUM_GIT_TOKEN` | Auth token for private repos |\n| `git_username` | `CORUM_GIT_USERNAME` | Auth username (default: `x-access-token`) |\n\nAdditional environment-only runtime settings:\n\n| Environment variable | Description |\n|---|---|\n| `CORUM_WEB_PORT` | Default port for `corum web` |\n| `CORUM_FILE_WATCHER` | Enable local file watching for filesystem graphs when running the web UI |\n| `CORUM_WATCH` | Alias for `CORUM_FILE_WATCHER` |\n\n### File source (default)\n\n```yaml\n# .corum/config.yaml\nsource: file\ngraph: .corum/graph\n```\n\nUse this when the graph lives directly on the local filesystem with no git source abstraction.\n\n### Git source\n\n```yaml\n# .corum/config.yaml\nsource: git\ngit_remote_url: https://github.com/org/design-repo\ngit_branch: main\ngit_poll_seconds: 30\n```\n\nOr for a local git repository:\n\n```yaml\n# .corum/config.yaml\nsource: git\ngit_local_path: /path/to/repo\ngit_branch: main\n```\n\nRules:\n- Set exactly one of `git_local_path` or `git_remote_url`.\n- `git_branch` selects the default branch Corum loads for read operations and the web UI.\n- `git_poll_seconds` is only used for git-backed web reloads.\n\nFor private repositories, set `CORUM_GIT_TOKEN` as an environment variable rather than storing it in the config file.\n\n## MCP Client Configuration\n\nConfigure your MCP client to run Corum. For Claude Code or Claude Desktop:\n\n```json\n{\n \"mcpServers\": {\n \"corum\": {\n \"command\": \"npx\",\n \"args\": [\"@atolis-hq/corum\", \"mcp\", \"--no-web\"],\n \"env\": {\n \"CORUM_GRAPH_PATH\": \"/path/to/your/graph\"\n }\n }\n }\n}\n```\n\nOr if installed globally:\n\n```json\n{\n \"mcpServers\": {\n \"corum\": {\n \"command\": \"corum\",\n \"args\": [\"mcp\", \"--no-web\"],\n \"env\": {\n \"CORUM_GRAPH_PATH\": \"/path/to/your/graph\"\n }\n }\n }\n}\n```\n\n## MCP Tools\n\n| Tool | Description |\n|---|---|\n| `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |\n| `list_templates` | List loaded templates with summary metadata |\n| `get_template` | Return full details for a template |\n| `get_cluster` | Return a node's structural contents. By default, schema and enum child nodes are collapsed into compact `schemas` and `enums` blocks on the root. Pass `collapse_schemas: false` to restore the full node-per-field representation |\n| `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |\n| `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |\n| `get_lineage` | Traverse lineage from one or more start nodes. Lean nodes and no `edges` by default; opt in to fuller payloads when needed |\n| `get_graph_summary` | Return high-level graph statistics: node count, component count, orphan breakdown, edge counts, diagnostics |\n| `search_nodes` | Fuzzy-search root-level nodes by ID, with optional template filters and property search |\n| `get_linked_fields` | Return `maps-to` edges touching fields owned by a root node |\n| `list_branches` | List available branches and their load status from the configured source |\n| `diff_branch` | Diff a branch against the default branch |\n| `start_changes` | Open a working mutation session |\n| `apply_cluster` | Upsert a cluster-style document in `merge` or `replace` mode |\n| `create_node` | Create a root cluster or owned child node |\n| `update_node` | Patch node properties, state, or stability |\n| `rename_node` | Rename a node while preserving identity trail metadata |\n| `delete_node` | Soft-delete or hard-delete a node subtree |\n| `create_edges` | Batch-create explicit edges as one atomic operation |\n| `update_edge` | Patch an explicit edge |\n| `delete_edge` | Delete an explicit edge |\n| `create_fields` | Batch-create fields across schemas (grouped and applied per parent) |\n| `pending_changes` | Show the open session's journal and summary diff |\n| `discard_changes` | Abort the working session |\n| `commit_changes` | Lint, serialize, and persist the session's changes |\n\nAll tools accept an optional `format` argument: `toon` (default; leanest for the LLM), `yaml`, or `json`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage further.\n\nAll node-returning MCP tools accept `include_provenance: true` to include `extractedFrom`, `lastModifiedAt`, `derivation`, and `derivedBy`. These fields are omitted by default. `schemaVersion` is never returned by MCP.\n\nCommon notes:\n- `branch` is supported on graph-query tools when Corum is running against a source-backed graph.\n- `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.\n- `search_nodes` accepts `queries: string[]`.\n- `get_graph_metadata` should usually be your first call. Use `edge_types_in_use` to avoid traversing edge types that do not exist in the current graph.\n- `get_graph_metadata` returns `valid_edge_types`, `states`, `stabilities`, `lineage_directions`, and `output_formats` when you pass `include_static_enums: true`.\n- Prefer `search_nodes` over `list_nodes` for discovery. Use `list_nodes` when you need a full inventory under explicit filters.\n- `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.\n- `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.\n- Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.\n- Use `get_cluster` only when you need full structural contents for one node. By default it returns compact `schemas` and `enums` blocks on the root rather than individual field nodes, which keeps response size manageable for large aggregates. Use `get_lineage` for relationship traversal.\n- Read tools reflect the open working session while one exists. Unbranched reads, and branch-scoped reads for that same session branch, show uncommitted changes.\n- The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.\n\n## MCP Write Workflow\n\nCorum's write tools are session-based:\n\n1. Call `start_changes`.\n2. Make one or more mutations with `apply_cluster`, `create_node`, `update_node`, `rename_node`, `delete_node`, `create_edges`, `update_edge`, `delete_edge`, or `create_fields`.\n3. Inspect the session with `pending_changes`.\n4. Finish with `commit_changes` or abort with `discard_changes`.\n\nImportant behavior:\n- No write tool works without an open session.\n- `rename_node` is the only rename path. `apply_cluster` and imports never infer renames.\n- `apply_cluster` `replace` mode is authoritative for the root's owned sections: absent children are deleted, and an absent owned section means \"empty section\".\n- `delete_node` defaults to soft delete for nodes that already exist on the default branch, and hard delete for branch-local design work.\n- `discard_changes` closes the session. On file-backed autosave sessions it does not roll back mutations already written through to disk.\n\nSource-mode defaults:\n- Filesystem source: `start_changes` defaults `autosave` on. Each mutation writes through immediately; `commit_changes` mainly lint-gates and closes the session.\n- Git source: `start_changes` defaults `autosave` off. Changes stay in memory until `commit_changes`.\n- Git source with `autosave: true`: each mutation creates a `corum-wip:` checkpoint commit; `commit_changes` squashes that run when no external commit interleaved.\n\nTypical sequence:\n\n```yaml\nstart_changes:\n branch: feat/order-design\n create: true\n\nrename_node:\n id: orders.Schema.invoice\n new_name: bill\n\npending_changes: {}\n\ncommit_changes:\n message: rename invoice schema to bill\n```\n\n## MCP Prompts\n\nThe server also exposes a discoverable MCP prompt:\n\n| Prompt | Description |\n|---|---|\n| `usage-guide` | Orientation guide covering graph structure, read and write workflow, output-format choices, graph-completeness caveats, and inference guidance |\n\n## Contributing\n\nSee [DEVELOPMENT.md](DEVELOPMENT.md) for build, test, and local development instructions.\n\n\n## Issues & Feature Requests\n\nFound a bug or have an idea for Corum? [Open an issue](https://github.com/atolis-hq/corum/issues/new) —\nbug reports and feature requests are both welcome.\n\n## License\n\nCorum is licensed under the [Apache License 2.0](LICENSE).\n","readmeFilename":"README.md"}]![](\"assets/corum-logo.svg\"){kind=logo}