archgraph-argo 0.27.0 → 0.28.0

package/README.md

@@ -1,106 +1,167 @@
 # ArchGraph
 
-An architecture-graph driven framework for Agentic Engineering.
+**A knowledge-graph framework with an ontology you define — wired into your coding agent through one MCP interface.**
+
+For teams running coding agents on a real codebase, ArchGraph gives the agent durable, tiered long-term memory on an **intent graph** — a versioned architecture graph that records *why* the system is built the way it is, not just how. You and the agent read and write it through a single **MCP** server (**MCP** = **Model Context Protocol**, the open standard that lets an AI tool call external servers as tools). The graph's shape is set by an **ontology** — its vocabulary of element and relationship types — and that ontology is yours to define. The built-in default is **ArchiMate 3.2 + ARGO extensions**, where **ArchiMate** is a standard enterprise-architecture modeling language and **ARGO** is the toolchain and agent-workflow layer behind the `argo-deploy` and `argo init` commands. A repository can plug in its own ontology — and this one does. **One install, one interface to learn.**
+
+Ready to try it? Jump to **[Build your own graph](#build-your-own-graph)**.
+
+[Install](#install) · [Build your own graph](#build-your-own-graph) · [Why ArchGraph](#why-archgraph) · [Capabilities](#capabilities) · [Docs](#docs) · [Community](#community)
+
+![ArchGraph core model — one graph for the agent's memory and the product's design](docs/diagrams/core-model.svg)
 
 ## What is this?
 
-ArchGraph builds a **unified language** that puts harness design and target product design into
-**one model** — so you get a single view to work and observe, and real control over your agents.
+If you run coding agents on a real codebase, every session starts cold and the "why" behind the system lives nowhere. ArchGraph makes **one architecture graph** the single source of truth — the agent's memory and the product's design in one model. It is *one MCP interface* to install and learn: the agent restores context at session start, recalls detail on demand, and reuses what it already knows instead of duplicating it (a duplicate needs an explicit override).
 
-It doubles as a **long-term memory for coding agents**: an ArchiMate 3.2 intent graph exposed through
-a single read/write MCP interface. Memory is tiered — a compact working memory restored at session
-start, a long-term memory recalled on demand — and writes are deduplicated, so the graph stays clean
-and semantic recall stays precise. Reusable subgraphs can also be shared across projects through a
-federated registry, and any read tool can take an optional <code>projectId</code> to query
-**another project's graph** through the federation center — authorized, read-only, and by
-reference (denied by default). See the [home page](https://archgraph.org/) for the full capability set.
+- **Architects / tech leads** — one model of the product, the harness, and the agents.
+- **Agent users** — memory restored at session start, recalled on demand, reused instead of duplicated.
+- **Platform teams** — one interface, deployed into the editor you already use.
 
-![ArchGraph core model — harness design and product design in one graph](docs/diagrams/core-model.svg)
+→ Full onboarding: **[docs/getting-started.html](docs/getting-started.html)**
 
-## Architecture
+## Why ArchGraph
 
-The global architecture (Layered Viewpoint) shows how the human, the coding agent, ARGO MCP, the
-intent architecture graph, ArchiMate 3.2, and Enterprise Architect relate in graph-driven agentic
-engineering:
+Every team running coding agents hits the same wall: the code is in the repo, but the *reasoning* behind it lives nowhere. Four common fixes exist, and each works until it doesn't.
 
-![Global architecture — Layered Viewpoint](docs/diagrams/global-architecture.svg)
+The real differentiator is **not** "custom vs. locked". Protégé/OWL, Neo4j, TerminusDB, and Archi/EA all let you extend a model or bring your own vocabulary. It is that ArchGraph makes the ontology a **first-class, validated, runtime-resolved schema bundle** — and puts it behind **one MCP interface** the agent reads *and* writes, with typed dedup and commit traceability built in.
 
-Editable source: [`scripts/gen-diagrams.js`](scripts/gen-diagrams.js)
+The honest, cost-included comparison lives in one canonical place — **[docs/capabilities.html#compare](docs/capabilities.html#compare)**.
 
-## Supported Harnesses
+## Bring your own ontology
 
-ArchGraph deploys the ARGO toolchain to all major coding-agent environments:
+A knowledge-graph framework that speaks only one language is not a framework. ArchGraph separates the **core** from the **ontology**: a repository drops a *schema bundle* under `.argo/schema/` (element/relationship types, endpoint rules, an actor contract, an optional guide), and validation, MCP guidance, and the `.qea` projection follow it. A bundle can `extends: "default"` — inheriting the built-in **ArchiMate 3.2 + ARGO extensions** — and add its own types; no framework change required.
 
-| Harness            | MCP Server | Skills | Rules / Instructions | Agents | Wakeup Gate |
-|--------------------|:----------:|:------:|:--------------------:|:------:|:-----------:|
-| GitHub Copilot     |     ✓      |   ✓    |          ✓           |   ✓    |      —      |
-| Cursor             |     ✓      |   ✓    |          ✓           |   ✓    |      —      |
-| OpenCode           |     ✓      |   ✓    |          ✓           |   ✓    |     ✓       |
-| DeepSeek Harness   |     ✓      |   ✓    |          ✓           |   ✓    |     ✓       |
-| OpenClaw           |     ✓      |   ✓    |          ✓           |   —    |     ✓       |
+This repository is the proof: its own bundle uses `extends: "default"` and layers a **UML 2 state-machine profile** on top, resolved at runtime from `.argo/schema/` rather than hardcoded in the framework.
 
-A single `argo-deploy` registers the `argo` MCP server and installs all artifacts into each harness
-automatically.
+→ Worked example — define an ontology, then build the graph step by step: **[docs/case-team-graph.html](docs/case-team-graph.html)** · runnable bundle: [`custom-schema/`](custom-schema/README.md)
 
 ## Install
 
-```powershell
+**Prerequisite: Node.js ≥ 18** (the ARGO toolchain and the MCP server both run on Node).
+
+```bash
 npm install -g archgraph-argo
 argo-deploy
 ```
 
-Done &mdash; the ARGO toolchain, skills, and rules are deployed, and the `argo` MCP server is registered automatically in **GitHub Copilot**, **Cursor**, **OpenCode**, **DeepSeek Harness** (dsh), and **OpenClaw**.
+`argo-deploy` registers the `argo` MCP server and installs the skills and rules into **GitHub Copilot, Cursor, OpenCode, DeepSeek Harness, OpenClaw, and Codex** (agents are installed where the host supports them). It then prompts for the few settings in `~/.argo/.env`. **After deploying, restart your editor / host** so it reloads the MCP server. Semantic queries additionally need **Neo4j** and an **embedding** endpoint — see [Build your own graph](#build-your-own-graph).
 
-### Prerequisites and configuration
+## Quick start
 
-Everything works out of the box except **semantic (Graph RAG) queries**, which need:
+There is **one** canonical start: **[Build your own graph](#build-your-own-graph)** — install once, then pick Route A (the default ontology) or Route B (your own). That section carries every step and MCP call; this one deliberately keeps no second copy, so there is only one path to follow.
 
-- **Neo4j graph database** — stores the structural projection of your architecture graph. During
-  `argo-deploy` you configure `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and
-  `ARGO_NEO4J_DATABASE_PASSWORD` in `~/.argo/.env`.
-- **Embedding / vector engine** — powers semantic Graph RAG retrieval. Configure
-  `ARGO_EMBEDDING_BASE_URL`, `ARGO_EMBEDDING_MODEL`, `ARGO_EMBEDDING_PROVIDER`,
-  `ARGO_EMBEDDING_MODEL_VERSION`, `ARGO_EMBEDDING_DIMENSIONS`, plus the API key `QWEN_KEY`.
-  It points at **any OpenAI-compatible embedding endpoint** — a cloud provider, or a self-hosted
-  server for offline / intranet / private deployments via `ARGO_EMBEDDING_PROFILE=openai-compatible`
-  (see the [self-hosted embedding guide](docs/self-hosted-embedding-deployment.md)).
+**The one prerequisite that is not out of the box:** semantic (Graph RAG) retrieval needs a **Neo4j** instance and an OpenAI-compatible **embedding** endpoint. Context reads, writes, and Enterprise Architect interop work without them; the **Cypher** (Neo4j's graph query language) structural projection and all semantic retrieval need Neo4j.
 
-Where do the values come from? The Neo4j credentials come from the Neo4j instance you own or
-provision (URI, username, password). The embedding configuration and `QWEN_KEY` come from your
-embedding provider's dashboard — for example Alibaba DashScope — or from a self-hosted
-OpenAI-compatible server. `argo-deploy` walks you through the prompt (existing non-empty values in
-`~/.argo/.env` are kept); you can also edit the file afterwards and re-run.
+## Build your own graph
 
-## How to use
+Pick **one** of two routes. Everything happens through your coding agent and the ARGO MCP server; the only commands you run yourself are the install. Once initialized, the intent graph is the single source of truth.
+
+### Route A — default ontology (fastest)
+
+No schema work: use the built-in **ArchiMate 3.2 + ARGO extensions**.
+
+1. **Install (once).** Requires **Node.js ≥ 18**.
+
+   ```bash
+   npm install -g archgraph-argo
+   argo-deploy
+   ```
+
+   Then **restart your editor / host** so it reloads the MCP server.
+
+2. **Initialize.** Ask your coding agent to run `argo init` (the `initializeWorkspace` MCP call). It creates and validates the starter `design/KG/SystemArchitecture.json`, which already contains the project's root view named `SystemArchitecture`.
+
+3. **Add elements and relationships.** Ask your coding agent to call `applySystemArchitectureMutation` and attach every new element and relationship to the project's **existing root view** — tell it to resolve that view's real `view_id` first (`queryNeo4jGraph` / `getArchitectureViewContext`). Do **not** pre-create a view: a new view called `SystemArchitecture` would collide with the one `argo init` made, and any `view_ids` pointing at a different id would then fail.
+
+4. **Verify.** Ask your coding agent to call `validateSystemArchitecture`, then `queryNeo4jGraph` with `{"schema": true}` to confirm the element and relationship types in effect.
+
+### Route B — your own ontology
+
+1. **Install (once).** As in Route A.
+
+2. **Author your schema.** Put your modeling language under `.argo/schema/`. A **standalone** bundle — a full `SystemArchitecture.schema.json`, editing its two `$defs` enum arrays, `archimateElementType` and `archimateRelationshipType` — **must also declare `actorElementType` in `schema-bundle.config.json`**, set to one of your element types (or to `null` if your schema genuinely has no actor concept), or loading fails closed (`bundleValidation.status: "failed"`) and validation/writes are blocked. A bundle that only `extends: "default"` needs just the config. `schema-bundle.rules.json` stays optional (without it, endpoint checks are permissive).
+
+3. **Author the graph yourself.** With a custom schema, `argo init` does **not** create the graph — the packaged default would not match your vocabulary — and it **fails closed** with `NO_DEFAULT_GRAPH`. Before any MCP write, create `design/KG/SystemArchitecture.json` by hand, using your own element and relationship types and your own root view. Then ask your coding agent to run `argo init` to validate it.
 
-**Step 0 — initialize the workspace.** In a fresh project, ask your coding agent to run `argo init`
-(the `initializeWorkspace` MCP call). It creates a starter `design/KG/SystemArchitecture.json` when
-missing, performs the first JSON → Neo4j sync, initializes the semantic (Graph RAG) lifecycle, and
-verifies the architecture. From then on, the intent graph is the source of truth for the project.
+4. **Add into YOUR root view.** Ask your coding agent to call `applySystemArchitectureMutation`, attaching each element and relationship to the root view **you authored** (not the default one).
 
-After installing, open your project and start a coding agent. It will:
+5. **Verify.** Ask your coding agent to call `validateSystemArchitecture`, then `queryNeo4jGraph` with `{"schema": true}`.
+
+The fully-illustrated, step-by-step walkthrough is **[docs/case-team-graph.html](docs/case-team-graph.html)** (Chinese), and the runnable example bundle is [`custom-schema/`](custom-schema/README.md). The result looks like this:
+
+![Team Graph example — Agent 001 assigned to Team A, Team A depends on Service A, Service A depends on Service B](docs/diagrams/team-graph-elements-relations.svg)
+
+## Capabilities
+
+Each line links to a short page — this is the map, not the manual.
+
+- **[Tiered long-term memory](docs/capabilities.html#memory)** — a compact working memory at session start, a long-term memory recalled on demand, and an archive.
+- **[Pluggable ontology](docs/capabilities.html#ontology)** — ship your own schema bundle; the default (ArchiMate 3.2 + ARGO extensions) is data, not code.
+- **[Semantic + structural retrieval](docs/capabilities.html#retrieval)** — Graph RAG recall plus read-only Cypher for exact structure.
+- **[Deduplicated writes](docs/capabilities.html#quality)** — reuse an existing element, relationship, or view instead of copying it; near-duplicates are blocked as candidates.
+- **[Acceptance-test-first + traceability](docs/capabilities.html#quality)** — every change is testable, and the commit id is registered back onto the element.
+- **[Enterprise Architect interop](docs/capabilities.html#interop)** — the graph projects to `.qea`; human EA edits return as a semantic diff.
+- **[Federated graph sharing](docs/capabilities.html#federation)** — sovereign graphs joined by a registry–broker; reads authorized and returned by reference.
+- **[One MCP interface, six hosts](docs/capabilities.html#harness)** — install once, run in Copilot, Cursor, OpenCode, DeepSeek Harness, OpenClaw, and Codex.
+
+## How to use
+
+**Initialize once** (`argo init`), then open your project and let your coding agent work. It will:
 
 1. locate the architecture element behind the task before changing anything,
 2. arm itself with that element's Skills and Rules,
-3. work test-first (GIVEN-WHEN-THEN), and trace every commit back to the graph,
-4. reuse an existing element, relationship, or view instead of creating a duplicate — the write path
-   deduplicates by identity and flags a semantically near element of the same type.
+3. work test-first (GIVEN-WHEN-THEN) and trace every commit back to the graph,
+4. reuse an existing element by default — a near-duplicate needs an explicit override.
 
-The intent architecture graph — modelled in **ArchiMate 3.2** — is the single source of truth.
+The intent architecture graph is the single source of truth.
+
+## Supported Harnesses
+
+| Harness | MCP | Skills | Rules | Agents |
+|---------|:---:|:------:|:-----:|:------:|
+| GitHub Copilot    | ✓ | ✓ | ✓ | ✓ |
+| Cursor            | ✓ | ✓ | ✓ | ✓ |
+| OpenCode          | ✓ | ✓ | ✓ | ✓ |
+| DeepSeek Harness  | ✓ | ✓ | ✓ | ✓ |
+| OpenClaw          | ✓ | ✓ | ✓ | — |
+| Codex             | ✓ | ✓ | ✓ | — |
+
+A single `argo-deploy` registers the `argo` MCP server and installs all artifacts into each harness automatically.
+
+## Cross-project read/write
+
+Cross-project access runs over **two separate channels** — they must not be conflated:
+
+1. **Local path** — a per-call `workspaceRoot` reads a peer project's graph on the same machine. Writes are **read-only by design**: a foreign write is refused with `WORKSPACE_WRITE_DENIED`.
+2. **Federated** — a per-call `projectId` is routed through the **federation center**, authorized there (denied by default), and returned by reference.
+
+Whether the local channel works depends on the harness, because a harness may bridge the MCP server and pin the workspace per call:
+
+| Harness | Local read (`workspaceRoot`) | Local write | Federated read (`projectId`) |
+|---------|:----------------------------:|:-----------:|:----------------------------:|
+| OpenCode         | ✓ | blocked (`WORKSPACE_WRITE_DENIED`) | ✓ |
+| Codex            | ✓ | blocked (`WORKSPACE_WRITE_DENIED`) | ✓ |
+| DeepSeek Harness | ✗ | ✗ | ✓ |
+| GitHub Copilot   | ✓ | blocked (`WORKSPACE_WRITE_DENIED`) | ✓ |
+| Cursor           | 待测 | 待测 | ✓ |
+| OpenClaw         | 不涉及 | 不涉及 | ✓ |
+
+DeepSeek Harness **cannot** do local cross-project access: its bridge pins the session workspace, so the request never reaches the server as written and only the federated channel works.
 
 ## Community
 
-ArchGraph runs on open co-building. Join the community hub to share, browse and reuse **architecture
-subgraphs** across projects, and follow the governance & contribution guides:
+ArchGraph runs on open co-building: share and reuse **architecture subgraphs** across projects. Sharing is **federated** — each project keeps its graph sovereign, and members register, discover, authorize, and read opened content **by reference** (denied by default; nothing copied or merged). The center is a **registry–broker** that holds federation metadata, never content.
+
+- **Community site** — https://argo.derekworkspacev5.com/archgraph/
+- **graph-wiki** (graph-asset home) — https://github.com/derekhu0002/graph-wiki
+- **GitHub** — https://github.com/derekhu0002/archgraph
 
-- **Community site** — https://argo.derekworkspacev5.com/archgraph/ (subgraph library, docs, blog)
-- **graph-wiki repository** — https://github.com/derekhu0002/graph-wiki (graph-asset home: contribute
-  a subgraph from your project, or pull one back to reuse)
+## Docs
 
-Sharing is **federated**: each project keeps its own graph sovereign and publishes subgraphs to a
-registry, where other members register, discover, and read opened content **by reference** —
-register, discover, authorize, read. Access is **denied by default**, and nothing is copied or merged.
-Browse the [federation members](https://argo.derekworkspacev5.com/archgraph/federation).
+- [Getting started](docs/getting-started.html) · [Capabilities](docs/capabilities.html) · [Worked case: Team Graph](docs/case-team-graph.html)
+- [Schema bundles / ontology decoupling](docs/schema-bundle-decoupling.md) · [Self-hosted embeddings](docs/self-hosted-embedding-deployment.md) · [MCP acceptance](docs/mcp-acceptance.md)
+- [Insights](docs/insights.html) — GraphRAG, agent memory, and portable skills.
 
 ## License
 

package/argo/.env.example

@@ -142,7 +142,7 @@ ARGO_W31_LIVE_MUTATION_VECTOR_E2E=
 # Pin the workspace/repository root the MCP server serves.
 # ARGO_REPO_ROOT=
 # Explicit schema-bundle directory (highest precedence): overrides both the
-# repository's own <workspace>/.argo/schema bundle and the default ArgoBument
+# repository's own <workspace>/.argo/schema bundle and the default ArchiMate 3.2
 # bundle. Must contain SystemArchitecture.schema.json.
 # ARGO_SCHEMA_DIR=
 # Actor element type the wakeup gate looks up when a workspace schema renames
@@ -168,3 +168,14 @@ ARGO_W31_LIVE_MUTATION_VECTOR_E2E=
 # ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD=
 # Alias of ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD (takes precedence when set).
 # ARGO_SEMANTIC_DEDUP_THRESHOLD=
+# Cross-project WRITE guard. Default ON: a write tool may only target the
+# server's own (home) workspace, so a foreign per-call workspaceRoot is
+# rejected fail-closed while cross-project READS stay open. "0" disables it
+# (all-or-nothing) for a trusted multi-workspace host that legitimately writes
+# several workspaces through one server.
+# ARGO_WORKSPACE_WRITE_GUARD=
+# Set to "1" by a trusted host broker (e.g. the DSH workspace bridge) to assert
+# it controls the per-call `sessionWorkspaceRoot` field; the argo server then
+# allows WRITES to that host-designated session workspace as well as its home
+# workspace. A model cannot set a process env var, so the trust is unforgeable.
+# ARGO_WORKSPACE_ROOT_TRUSTED=

package/argo/rules/archgraph.instructions.md

@@ -30,7 +30,7 @@ Non-negotiable red lines (MUST). Never skip, simplify, or silently violate them;
 
 <Ontology>
 Resolve the workspace modeling language before acting; do not assume ArchiMate. `queryNeo4jGraph` with `{schema:true}` returns `schemaKind`, `schemaLanguage`, the element/relationship type enums, `actorElementType`, `bundleValidation` and `guidePath`.
-1. `schemaKind` `default`: the built-in ArgoBument language (ArchiMate 3.2 + ARGO). Reference files under ~/.argo: structure `~/.argo/schema/SystemArchitecture.schema.json`; types `~/.argo/schema/archimate3.2.md`.
+1. `schemaKind` `default`: the built-in ArchiMate 3.2 modeling language (with ARGO extensions). Reference files under ~/.argo: structure `~/.argo/schema/SystemArchitecture.schema.json`; types `~/.argo/schema/archimate3.2.md`.
 2. `schemaKind` `workspace`/`override`: the repository's own schema bundle. Its element/relationship types, endpoint rules, root-view name, per-view element limit and guide govern every read and write — never assume ArchiMate types here.
 3. `actorElementType` is the element type whose members are Actors (default `Business Actor`; `null` = no actor concept → skip Actor identification). Host override: ARGO_ACTOR_ELEMENT_TYPE.
 4. If `bundleValidation.status` is `failed`, the workspace schema is misconfigured: report it to the human partner and do not write until it is fixed.

package/argo/schema/{argob.config.json → schema-bundle.config.json}

@@ -1,7 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "ArgoBument default schema bundle descriptor",
-  "description": "Descriptor for the default ARGO schema bundle (ArchiMate 3.2 + ARGO extensions). A repository may override this bundle by placing its own SystemArchitecture.schema.json (plus an optional argob.config.json / argob-rules.json) under <workspace>/.argo/schema.",
+  "title": "ArchiMate 3.2 default schema bundle descriptor",
+  "description": "Descriptor for the default ARGO schema bundle (ArchiMate 3.2 + ARGO extensions). A repository may override this bundle by placing its own SystemArchitecture.schema.json (plus an optional schema-bundle.config.json / schema-bundle.rules.json) under <workspace>/.argo/schema.",
+  "id": "default",
+  "aliases": ["archimate3.2", "archimate", "base"],
   "language": "ArchiMate 3.2",
   "elementTypeEnumKey": "archimateElementType",
   "relationshipTypeEnumKey": "archimateRelationshipType",