archgraph-argo 0.26.2 → 0.28.0

package/README.md

@@ -1,97 +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. Writes are deduplicated, so the graph stays clean and semantic
-recall stays precise. 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.
 
-![alt text](docs/diagrams/image.png)
+→ 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: [`docs/diagrams/global-architecture.excalidraw`](docs/diagrams/global-architecture.excalidraw)
+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 — 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.
+
+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).
 
-**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.
+5. **Verify.** Ask your coding agent to call `validateSystemArchitecture`, then `queryNeo4jGraph` with `{"schema": true}`.
 
-After installing, open your project and start a coding agent. It will:
+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 is the single source of truth.
+
+## Supported Harnesses
 
-The intent architecture graph — modelled in **ArchiMate 3.2** — is the single source of truth.
+| 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
+
+## Docs
 
-- **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)
+- [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

@@ -1,163 +1,181 @@
-# =============================================================================
-# ArchGraph (archgraph-argo) environment configuration — EXAMPLE.
-#
-# Copy this file to the live env file and fill in real values:
-#   Windows      %USERPROFILE%\.argo\.env
-#   Linux/macOS  ~/.argo/.env
-# The live file is git-ignored and MUST stay untracked with a restricted ACL;
-# this example is committed and contains no secrets.
-#
-# PART 1 keys are the ONLY keys accepted inside the .env file (any unknown key
-# makes the secret-file preflight reject the whole file). PART 2 keys are
-# host/process-level only — set them in the host/MCP launch config or shell, NOT
-# here. Empty values below are placeholders.
-# =============================================================================
-
-
-# -----------------------------------------------------------------------------
-# PART 1 — .env file keys
-# -----------------------------------------------------------------------------
-
-# --- Embedding provider (required) — powers vector semantic retrieval -------
-# Provider profile: "approved" (default) = the human-approved cloud profile
-# below; "openai-compatible" = a self-hosted OpenAI-compatible endpoint
-# (intranet/offline) whose URL/model/label/dimension are read verbatim.
-ARGO_EMBEDDING_PROFILE=
-# OpenAI-compatible embedding endpoint base URL (no trailing slash).
-ARGO_EMBEDDING_BASE_URL=
-# Embedding model id (e.g. qwen3.7-text-embedding).
-ARGO_EMBEDDING_MODEL=
-# Provider label recorded in evidence; also the rerank fallback provider.
-ARGO_EMBEDDING_PROVIDER=
-# Model version / qualification label (recorded evidence only).
-ARGO_EMBEDDING_MODEL_VERSION=
-# Embedding vector dimension; must match the model and the vector index
-# (current profiles: 1536).
-ARGO_EMBEDDING_DIMENSIONS=
-# Query-side instruction prefix for instruction-tuned embedding models (e.g.
-# gte-Qwen2: "Instruct: <task>\nQuery: "). Empty = no prefix. Documents are
-# never prefixed; only the query side is.
-ARGO_EMBEDDING_QUERY_INSTRUCTION=
-# Optional embedding API key. SECRET: overrides QWEN_KEY as the Bearer token for
-# the embeddings call when set (useful for a self-hosted endpoint). Leave empty
-# to use QWEN_KEY.
-ARGO_EMBEDDING_API_KEY=
-
-# --- Neo4j (required) — structural projection + vector/full-text store ------
-# Neo4j connection URI (e.g. neo4j://127.0.0.1:7687).
-ARGO_NEO4J_DATABASE_URL=
-# Neo4j username.
-ARGO_NEO4J_DATABASE_USERNAME=
-# Neo4j password. SECRET: value must come from the untracked, ACL-restricted
-# .env (or direct process injection) only — never commit it.
-ARGO_NEO4J_DATABASE_PASSWORD=
-# Optional: override the Neo4j database name. Default = sanitized repository
-# folder name (e.g. repo "archgraph" -> database "archgraph").
-ARGO_NEO4J_DATABASE=
-
-# --- Secrets (required) ------------------------------------------------------
-# API key for the embedding endpoint above. SECRET; also the fallback key for
-# the reranker when ARGO_RERANK_API_KEY is not set. Never commit it.
-QWEN_KEY=
-
-# --- Semantic retrieval tuning (optional; safe defaults shown) --------------
-# Similarity threshold, memory purposes (recall-oriented). Default 0.55.
-ARGO_SEMANTIC_MEMORY_THRESHOLD=
-# Memory threshold override for the Element channel. Default 0.55.
-ARGO_SEMANTIC_MEMORY_THRESHOLD_ELEMENT=
-# Memory threshold override for the ArchitectureRelationship channel. Default 0.55.
-ARGO_SEMANTIC_MEMORY_THRESHOLD_RELATIONSHIP=
-# Memory threshold override for the View channel. Default 0.55.
-ARGO_SEMANTIC_MEMORY_THRESHOLD_VIEW=
-# Similarity threshold, audit purpose (precision-oriented). Default 0.8.
-ARGO_SEMANTIC_AUDIT_THRESHOLD=
-# Audit threshold override for the Element channel. Default 0.8.
-ARGO_SEMANTIC_AUDIT_THRESHOLD_ELEMENT=
-# Audit threshold override for the ArchitectureRelationship channel. Default 0.8.
-ARGO_SEMANTIC_AUDIT_THRESHOLD_RELATIONSHIP=
-# Audit threshold override for the View channel. Default 0.8.
-ARGO_SEMANTIC_AUDIT_THRESHOLD_VIEW=
-# Bound on returned candidates per retrieval. Default 8.
-ARGO_SEMANTIC_TOP_K=
-
-# --- Hybrid retrieval (vector + lexical BM25 via RRF; optional) -------------
-# Master switch. "1" enables hybrid fusion; unset/"0" = vector-only (default off).
-ARGO_SEMANTIC_HYBRID=
-# Weight of the vector channel in the RRF fusion. Default 3.
-ARGO_SEMANTIC_HYBRID_VECTOR_WEIGHT=
-# Weight of the lexical (full-text) channel in the RRF fusion. Default 1.
-ARGO_SEMANTIC_HYBRID_LEXICAL_WEIGHT=
-# RRF smoothing constant k. Default 60.
-ARGO_SEMANTIC_HYBRID_RRF_K=
-# Candidate pool size pulled per channel before fusion. Default 16.
-ARGO_SEMANTIC_HYBRID_TOP_K=
-
-# --- LLM rerank (second-stage reordering; optional) -------------------------
-# Master switch. "1" enables rerank; unset/"0" = off (default off). Fail-open:
-# any error/timeout keeps the original order.
-ARGO_SEMANTIC_RERANK=
-# Rerank model when using the embedding provider fallback. Default qwen-turbo.
-ARGO_SEMANTIC_RERANK_MODEL=
-# Candidate pool size offered to the reranker. Default 20.
-ARGO_SEMANTIC_RERANK_POOL=
-# Max ids the reranker may return. Default 8.
-ARGO_SEMANTIC_RERANK_RETURN=
-# Per-request rerank timeout in ms (AbortController). Default 3500.
-ARGO_SEMANTIC_RERANK_TIMEOUT_MS=
-# Dedicated rerank provider (optional). When unset, rerank falls back to the
-# embedding provider above. Use these to point rerank at another provider/model
-# (e.g. DeepSeek: base https://api.deepseek.com, model deepseek-flash).
-ARGO_RERANK_BASE_URL=
-# Dedicated rerank API key. SECRET. Falls back to QWEN_KEY when unset.
-ARGO_RERANK_API_KEY=
-# Dedicated rerank provider label (informational; defaults to the embedding provider label).
-ARGO_RERANK_PROVIDER=
-# Dedicated rerank model id (overrides ARGO_SEMANTIC_RERANK_MODEL).
-ARGO_RERANK_MODEL=
-# Disable the rerank model's hidden "thinking"/reasoning (reasoning models spend
-# 6-12s per call for a listwise ranking with no accuracy gain). Default 1 =
-# disabled; set 0 to send nothing. Applies to every provider so a model swap
-# keeps the fast path. If a provider rejects the fragment it is retried without.
-ARGO_RERANK_DISABLE_THINKING=
-# Exact JSON body fragment merged into the rerank request to disable thinking
-# (default {"thinking":{"type":"disabled"}}). Override for another model/provider
-# that uses a different field, e.g. {"reasoning_effort":"none"} or
-# {"enable_thinking":false}.
-ARGO_RERANK_THINKING_PARAM=
-
-# --- Live end-to-end opt-ins (optional; normally unset) ---------------------
-# "1" allows the live embedding-provider E2E to hit the real network.
-ARGO_LIVE_PROVIDER_E2E=
-# "1" allows the live W3.1 mutation-vector E2E to hit the real network.
-ARGO_W31_LIVE_MUTATION_VECTOR_E2E=
-
-
-# -----------------------------------------------------------------------------
-# PART 2 — host / process-level only (do NOT put these in .env)
-# Set in the host or MCP launch configuration (mcp.json / opencode.json env,
-# dsh plugin, or the shell), never in the .env file.
-# -----------------------------------------------------------------------------
-# Point at a non-default env file path.
-# ARGO_ENV_FILE=
-# Pin the workspace/repository root the MCP server serves.
-# ARGO_REPO_ROOT=
-# Path to the Enterprise Architect model file (.qea) to project to/from.
-# ARGO_EA_QEA=
-# Semicolon-separated roots for multi-workspace hosts (DSH plugin).
-# ARGO_WORKSPACE_ROOTS=
-# Explicit path to the argo MCP server entry script (DSH plugin).
-# ARGO_SERVER_PATH=
-# URL of the graph-mcp HTTP bridge.
-# GRAPH_MCP_URL=
-# "1" enables verbose EA <-> .qea sync debug logging.
-# EA_QEA_DEBUG=
-# Architecture test runner timeout in ms.
-# ARGO_TEST_TIMEOUT_MS=
-# "1" prints the full mutation response for debugging.
-# ARGO_MCP_MUTATION_RESPONSE_DEBUG=
-# "0" disables the pre-write semantic dedup advisory (default: enabled).
-# ARGO_MCP_SEMANTIC_DEDUP=
-# Similarity threshold for the semantic dedup advisory. Default 0.85.
-# ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD=
-# Alias of ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD (takes precedence when set).
-# ARGO_SEMANTIC_DEDUP_THRESHOLD=
+# =============================================================================
+# ArchGraph (archgraph-argo) environment configuration — EXAMPLE.
+#
+# Copy this file to the live env file and fill in real values:
+#   Windows      %USERPROFILE%\.argo\.env
+#   Linux/macOS  ~/.argo/.env
+# The live file is git-ignored and MUST stay untracked (never commit it);
+# this example is committed and contains no secrets.
+#
+# PART 1 keys are the ONLY keys accepted inside the .env file (any unknown key
+# makes the secret-file preflight reject the whole file). PART 2 keys are
+# host/process-level only — set them in the host/MCP launch config or shell, NOT
+# here. Empty values below are placeholders.
+# =============================================================================
+
+
+# -----------------------------------------------------------------------------
+# PART 1 — .env file keys
+# -----------------------------------------------------------------------------
+
+# --- Embedding provider (required) — powers vector semantic retrieval -------
+# Provider profile: "approved" (default) = the human-approved cloud profile
+# below; "openai-compatible" = a self-hosted OpenAI-compatible endpoint
+# (intranet/offline) whose URL/model/label/dimension are read verbatim.
+ARGO_EMBEDDING_PROFILE=
+# OpenAI-compatible embedding endpoint base URL (no trailing slash).
+ARGO_EMBEDDING_BASE_URL=
+# Embedding model id (e.g. qwen3.7-text-embedding).
+ARGO_EMBEDDING_MODEL=
+# Provider label recorded in evidence; also the rerank fallback provider.
+ARGO_EMBEDDING_PROVIDER=
+# Model version / qualification label (recorded evidence only).
+ARGO_EMBEDDING_MODEL_VERSION=
+# Embedding vector dimension; must match the model and the vector index
+# (current profiles: 1536).
+ARGO_EMBEDDING_DIMENSIONS=
+# Query-side instruction prefix for instruction-tuned embedding models (e.g.
+# gte-Qwen2: "Instruct: <task>\nQuery: "). Empty = no prefix. Documents are
+# never prefixed; only the query side is.
+ARGO_EMBEDDING_QUERY_INSTRUCTION=
+# Optional embedding API key. SECRET: overrides QWEN_KEY as the Bearer token for
+# the embeddings call when set (useful for a self-hosted endpoint). Leave empty
+# to use QWEN_KEY.
+ARGO_EMBEDDING_API_KEY=
+
+# --- Neo4j (required) — structural projection + vector/full-text store ------
+# Neo4j connection URI (e.g. neo4j://127.0.0.1:7687).
+ARGO_NEO4J_DATABASE_URL=
+# Neo4j username.
+ARGO_NEO4J_DATABASE_USERNAME=
+# Neo4j password. SECRET: value must come from the untracked
+# .env (or direct process injection) only — never commit it.
+ARGO_NEO4J_DATABASE_PASSWORD=
+# Optional: override the Neo4j database name. Default = sanitized repository
+# folder name (e.g. repo "archgraph" -> database "archgraph").
+ARGO_NEO4J_DATABASE=
+
+# --- Secrets (required) ------------------------------------------------------
+# API key for the embedding endpoint above. SECRET; also the fallback key for
+# the reranker when ARGO_RERANK_API_KEY is not set. Never commit it.
+QWEN_KEY=
+
+# --- Semantic retrieval tuning (optional; safe defaults shown) --------------
+# Similarity threshold, memory purposes (recall-oriented). Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD=
+# Memory threshold override for the Element channel. Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD_ELEMENT=
+# Memory threshold override for the ArchitectureRelationship channel. Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD_RELATIONSHIP=
+# Memory threshold override for the View channel. Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD_VIEW=
+# Similarity threshold, audit purpose (precision-oriented). Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD=
+# Audit threshold override for the Element channel. Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD_ELEMENT=
+# Audit threshold override for the ArchitectureRelationship channel. Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD_RELATIONSHIP=
+# Audit threshold override for the View channel. Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD_VIEW=
+# Bound on returned candidates per retrieval. Default 8.
+ARGO_SEMANTIC_TOP_K=
+
+# --- Hybrid retrieval (vector + lexical BM25 via RRF; optional) -------------
+# Master switch. "1" enables hybrid fusion; unset/"0" = vector-only (default off).
+ARGO_SEMANTIC_HYBRID=
+# Weight of the vector channel in the RRF fusion. Default 3.
+ARGO_SEMANTIC_HYBRID_VECTOR_WEIGHT=
+# Weight of the lexical (full-text) channel in the RRF fusion. Default 1.
+ARGO_SEMANTIC_HYBRID_LEXICAL_WEIGHT=
+# RRF smoothing constant k. Default 60.
+ARGO_SEMANTIC_HYBRID_RRF_K=
+# Candidate pool size pulled per channel before fusion. Default 16.
+ARGO_SEMANTIC_HYBRID_TOP_K=
+
+# --- LLM rerank (second-stage reordering; optional) -------------------------
+# Master switch. "1" enables rerank; unset/"0" = off (default off). Fail-open:
+# any error/timeout keeps the original order.
+ARGO_SEMANTIC_RERANK=
+# Rerank model when using the embedding provider fallback. Default qwen-turbo.
+ARGO_SEMANTIC_RERANK_MODEL=
+# Candidate pool size offered to the reranker. Default 20.
+ARGO_SEMANTIC_RERANK_POOL=
+# Max ids the reranker may return. Default 8.
+ARGO_SEMANTIC_RERANK_RETURN=
+# Per-request rerank timeout in ms (AbortController). Default 3500.
+ARGO_SEMANTIC_RERANK_TIMEOUT_MS=
+# Dedicated rerank provider (optional). When unset, rerank falls back to the
+# embedding provider above. Use these to point rerank at another provider/model
+# (e.g. DeepSeek: base https://api.deepseek.com, model deepseek-flash).
+ARGO_RERANK_BASE_URL=
+# Dedicated rerank API key. SECRET. Falls back to QWEN_KEY when unset.
+ARGO_RERANK_API_KEY=
+# Dedicated rerank provider label (informational; defaults to the embedding provider label).
+ARGO_RERANK_PROVIDER=
+# Dedicated rerank model id (overrides ARGO_SEMANTIC_RERANK_MODEL).
+ARGO_RERANK_MODEL=
+# Disable the rerank model's hidden "thinking"/reasoning (reasoning models spend
+# 6-12s per call for a listwise ranking with no accuracy gain). Default 1 =
+# disabled; set 0 to send nothing. Applies to every provider so a model swap
+# keeps the fast path. If a provider rejects the fragment it is retried without.
+ARGO_RERANK_DISABLE_THINKING=
+# Exact JSON body fragment merged into the rerank request to disable thinking
+# (default {"thinking":{"type":"disabled"}}). Override for another model/provider
+# that uses a different field, e.g. {"reasoning_effort":"none"} or
+# {"enable_thinking":false}.
+ARGO_RERANK_THINKING_PARAM=
+
+# --- Live end-to-end opt-ins (optional; normally unset) ---------------------
+# "1" allows the live embedding-provider E2E to hit the real network.
+ARGO_LIVE_PROVIDER_E2E=
+# "1" allows the live W3.1 mutation-vector E2E to hit the real network.
+ARGO_W31_LIVE_MUTATION_VECTOR_E2E=
+
+
+# -----------------------------------------------------------------------------
+# PART 2 — host / process-level only (do NOT put these in .env)
+# Set in the host or MCP launch configuration (mcp.json / opencode.json env,
+# dsh plugin, or the shell), never in the .env file.
+# -----------------------------------------------------------------------------
+# Point at a non-default env file path.
+# ARGO_ENV_FILE=
+# 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 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
+# it. Default: Business Actor.
+# ARGO_ACTOR_ELEMENT_TYPE=
+# Path to the Enterprise Architect model file (.qea) to project to/from.
+# ARGO_EA_QEA=
+# Semicolon-separated roots for multi-workspace hosts (DSH plugin).
+# ARGO_WORKSPACE_ROOTS=
+# Explicit path to the argo MCP server entry script (DSH plugin).
+# ARGO_SERVER_PATH=
+# URL of the graph-mcp HTTP bridge.
+# GRAPH_MCP_URL=
+# "1" enables verbose EA <-> .qea sync debug logging.
+# EA_QEA_DEBUG=
+# Architecture test runner timeout in ms.
+# ARGO_TEST_TIMEOUT_MS=
+# "1" prints the full mutation response for debugging.
+# ARGO_MCP_MUTATION_RESPONSE_DEBUG=
+# "0" disables the pre-write semantic dedup advisory (default: enabled).
+# ARGO_MCP_SEMANTIC_DEDUP=
+# Similarity threshold for the semantic dedup advisory. Default 0.85.
+# 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=