project-atlas 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-05-22
+
+- Fixed proposal freshness checks so `apply` blocks when the base commit or source file hashes changed after proposal creation.
+- Added proposal-level `source_hashes` snapshots to the public proposal schema.
+- Fixed `review-summary` apply safety so missing source and missing metadata in non-scaffold knowledge documents block apply.
+- Included `docs/site` in the npm package because README links to the documentation site.
+- Simplified `npm run verify` to avoid running the build step twice.
+- Added project memory proposal generation through `project-atlas remember`.
+- Added `project-atlas check` for knowledge health checks.
+- Added context filters and JSON metadata for project memory documents.
+- Added MCP tools for remember and check without changing the terminal apply boundary.
+- Added `schema/memory-candidate.schema.json`.
+- Hardened memory and proposal inputs by rejecting unsafe source paths, frontmatter line breaks, duplicate targets, and boolean flag values.
+- Rewrote README in Chinese and added a concrete npm publishing guide.
+- Renamed the project, package, CLI, MCP server, adapter tools, and local evidence directory to Project Atlas.
+- Added bilingual documentation entry points and agent-first quick onboarding docs.
+- Added the first `project-atlas` CLI with `init`, `scan`, `context`, `stale`, `propose`, `apply`, `review-summary`, `cleanup`, and `hash`.
+- Added Git-first knowledge layout under `knowledge/` and local proposal evidence under `.project-atlas/proposals/`.
+- Added interactive TTY-only `apply` flow for generated knowledge changes.
+- Added OpenCode adapter examples for scan, context, and proposal generation without an apply tool.
+- Added JSON Schemas for manifest, proposal, trigger result, and context pack outputs.
+- Added context source lookup, multi-keyword query, stale suggestions, review summary safety sections, and init templates.
+- Added optional external evidence import for scan and proposal review.
+- Added local stdio MCP server and Claude Code, Cursor, and Continue adapter docs without model-callable apply.
+- Added Markdown documentation site, GitHub Actions CI, and release governance notes.
+- Updated the supported Node.js engine to `>=22`.

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thanks for helping improve Project Atlas.
+
+Project Atlas is a Git-first project knowledge base CLI for AI coding agents and engineering teams. Its core boundary is simple: agents may read context and create proposals, but only a human should run `project-atlas apply` in a terminal.
+
+## Local Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Checks
+
+Run these checks before opening a pull request:
+
+```bash
+npm run lint:types
+npm test
+npm run verify
+npm pack --dry-run
+node dist/index.js --help
+node dist/mcp.js --help
+```
+
+## Pull Request Rules
+
+- Keep changes small and focused.
+- Add or update tests for CLI behavior, schema behavior, adapters, and safety boundaries.
+- Update `docs/development-log/` for notable implementation work.
+- Do not add a model-callable apply tool.
+- Do not make `project-atlas apply` run without human terminal confirmation.
+- Do not commit `.project-atlas/`, `.code-review-graph/`, `node_modules/`, or local credentials.
+
+## Documentation
+
+Human-facing documentation may be bilingual. Agent-facing documentation should be plain English so it can be reused across tools and teams.
+
+Important entry points:
+
+- `README.md`
+- `docs/site/README.md`
+- `docs/site/agent-quickstart.md`
+- `docs/site/en/README.md`
+
+## Release
+
+Project maintainers publish manually:
+
+```bash
+npm run verify
+npm pack --dry-run
+npm publish
+git tag v<version>
+git push origin main --tags
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 project-atlas contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+# Project Atlas
+
+Project Atlas 是一个 Git 优先的项目知识库治理 CLI，面向 AI 编程 agent 和人工 reviewer。npm 包名是 `project-atlas`。
+
+CLI 命令名是 `project-atlas`。本地 MCP server 命令名是 `project-atlas-mcp`。项目把长期知识放在 `knowledge/`，把本地 proposal 证据放在 `.project-atlas/proposals/`，并要求真实写入必须由人在终端 TTY 中确认。
+
+## 解决什么问题
+
+- 减少 AI 每次任务都重新通读项目的成本。
+- 用 `knowledge/` 保存可复用的项目知识和项目级记忆。
+- 通过 source files、hash、proposal 和 trigger evidence 让知识更新可审查。
+- 保持安全边界，模型不能直接写入知识库。
+- 让 reviewer 通过 `review-summary` 快速判断 proposal 是否可 apply。
+
+## 文档入口
+
+先看 [docs/site/README.md](docs/site/README.md)。里面包含快速开始、最佳实践、团队落地、安全 FAQ 和发布流程。
+
+Agent 自动接入优先看 [docs/site/agent-quickstart.md](docs/site/agent-quickstart.md)。这份文档给 agent 用，包含首轮探测、只读上下文、proposal 生成和禁止 apply 的规则。
+
+English docs start at [docs/site/en/README.md](docs/site/en/README.md). Agent-first onboarding is available at [docs/site/en/agent-quickstart.md](docs/site/en/agent-quickstart.md).
+
+如果现在准备发布 npm 包，直接看 [docs/site/publish-now.md](docs/site/publish-now.md)。
+
+开源协作请看 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题和 agent 写入边界请看 [SECURITY.md](SECURITY.md)。
+
+## 常用命令
+
+```bash
+npm install
+npm run build
+
+node dist/index.js init --repo /path/to/repo --template java-backend
+node dist/index.js scan --repo /path/to/repo --mode full --external-evidence-file evidence.json
+node dist/index.js context --repo /path/to/repo --query "order payment" --budget 8000
+node dist/index.js context --repo /path/to/repo --source-file README.md --format json
+node dist/index.js stale --repo /path/to/repo
+node dist/index.js propose --repo /path/to/repo --updates-file updates.json --external-evidence-file evidence.json --reason "update project knowledge" --inherit-source-metadata
+node dist/index.js remember --repo /path/to/repo --candidate-file memory.json --reason "capture project memory"
+node dist/index.js check --repo /path/to/repo --format json
+node dist/index.js review-summary --repo /path/to/repo
+node dist/index.js apply --repo /path/to/repo --proposal-id <id> --confirm
+node dist/mcp.js --help
+```
+
+安装成 npm 包后，用 `project-atlas` 替代 `node dist/index.js`。
+
+```bash
+project-atlas --help
+project-atlas-mcp --help
+```
+
+## 知识库结构
+
+`project-atlas init` 会创建：
+
+- `knowledge/project/overview.md`
+- `knowledge/domains/`
+- `knowledge/workflows/`
+- `knowledge/contracts/`
+- `knowledge/integrations/`
+- `knowledge/quality/`
+- `knowledge/decisions/`
+
+生成的知识文档使用 YAML frontmatter，包含 `source_files`、`source_hashes`、`generated_by` 和 `review_status`。项目记忆文档还可以包含 `memory_type`、`topic`、`scope`、`confidence`、`owner` 和 `related_docs`。
+
+`project-atlas init` 支持三种模板：
+
+- `generic-service`
+- `java-backend`
+- `frontend-app`
+
+模板只影响初始说明和示例问题，不改变 `knowledge/` 目录结构，也不会覆盖已有文件。
+
+## 上下文和审查
+
+`project-atlas context` 支持多个关键词，默认任一关键词命中即可返回。来源优先级是 active OpenSpec changes、archived OpenSpec specs、`knowledge/`。
+
+按来源文件反查知识文档：
+
+```bash
+project-atlas context --repo /path/to/repo --source-file README.md --format json
+```
+
+按项目记忆元数据过滤：
+
+```bash
+project-atlas context --repo /path/to/repo --memory-type decision --topic payment --scope backend --format json
+```
+
+JSON context pack 会返回 `source_type`、`truncated` 和 `budget_used`，方便 agent 判断内容来源和是否被截断。
+
+`project-atlas stale` 会给出 stale、missing source 和 missing metadata 的建议动作。`project-atlas review-summary` 会输出 dry-run 规模、review decision 和 apply safety。
+
+健康检查：
+
+```bash
+project-atlas check --repo /path/to/repo --format json
+```
+
+更新已有知识文件时，可以显式继承旧来源信息：
+
+```bash
+project-atlas propose --repo /path/to/repo --updates-file updates.json --reason "refresh order knowledge" --inherit-source-metadata
+```
+
+## 项目级记忆
+
+项目级记忆是团队共享记忆，仍然存放在 `knowledge/`。它不是个人长期记忆库，也不读取聊天记录。
+
+`remember` 只接收结构化 JSON 候选文件，校验后生成 proposal，不直接写知识文件。
+
+```bash
+project-atlas remember --repo /path/to/repo --candidate-file memory.json --reason "capture project memory"
+```
+
+候选文件示例：
+
+```json
+{
+  "schema_version": "1.0",
+  "source_files": ["docs/development-log/2026-05-22-example.md"],
+  "memories": [
+    {
+      "target": "knowledge/decisions/payment-review.md",
+      "memory_type": "decision",
+      "topic": "payment review",
+      "scope": "backend",
+      "confidence": 0.9,
+      "summary": "Payment review must check duplicate callbacks.",
+      "body": "When changing payment callbacks, review duplicate notification handling before changing signature validation.",
+      "owner": "platform-team",
+      "related_docs": ["knowledge/workflows/payment.md"]
+    }
+  ]
+}
+```
+
+记忆类型：
+
+- `decision` 表示长期有效的决策。
+- `experience` 表示已完成任务里的经验。
+- `project_fact` 表示稳定项目事实。
+
+## 外部证据
+
+`scan` 和 `propose` 可以导入外部代码证据：
+
+```bash
+project-atlas scan --repo /path/to/repo --external-evidence-file evidence.json
+project-atlas propose --repo /path/to/repo --updates-file updates.json --external-evidence-file evidence.json --reason "refresh knowledge"
+```
+
+外部证据文件结构：
+
+```json
+{
+  "schema_version": "1.0",
+  "external_evidence": [
+    {
+      "source": "aider-repo-map",
+      "source_type": "repo_map",
+      "path": "src/main/java/com/example/OrderService.java",
+      "symbol": "OrderService",
+      "summary": "Order service owns order planning rules.",
+      "locator": "src/main/java/com/example/OrderService.java#L12",
+      "confidence": 0.86
+    }
+  ]
+}
+```
+
+外部工具不是硬依赖。没有外部证据时，`external_evidence` 是空数组。
+
+## JSON Schema
+
+npm 包会携带 JSON Schema draft 2020-12 文件：
+
+- `schema/manifest.schema.json`
+- `schema/proposal.schema.json`
+- `schema/trigger-result.schema.json`
+- `schema/context-pack.schema.json`
+- `schema/external-evidence.schema.json`
+- `schema/memory-candidate.schema.json`
+
+当前公开 schema 版本是 `1.0`。补充描述不需要升级 schema 版本。不兼容字段变更必须升级 schema 版本，并在 changelog 写清迁移方式。
+
+## OpenCode 适配器
+
+OpenCode adapter 是示例适配层，只暴露 scan、context 和 propose，不暴露 apply。
+
+先安装 `project-atlas`，再把这些目录复制到团队使用的 OpenCode 资产位置：
+
+```text
+adapters/opencode/tools
+adapters/opencode/commands
+adapters/opencode/skills
+```
+
+临时项目验收：
+
+```bash
+project-atlas init --repo /tmp/project-atlas-demo
+project-atlas scan --repo /tmp/project-atlas-demo --mode full
+project-atlas context --repo /tmp/project-atlas-demo --query demo
+project-atlas propose --repo /tmp/project-atlas-demo --updates-file updates.json --reason "demo update"
+```
+
+proposal 输出必须提示用户回到终端执行 `project-atlas apply`。
+
+## MCP 和 Agent 适配器
+
+`project-atlas-mcp` 启动本地 stdio MCP server。它只暴露：
+
+- `project_atlas_scan`
+- `project_atlas_context`
+- `project_atlas_stale`
+- `project_atlas_propose`
+- `project_atlas_remember`
+- `project_atlas_check`
+- `project_atlas_review_summary`
+
+它不暴露 apply。proposal 仍然必须人工 review，并由人在终端执行 apply。
+
+Claude Code：
+
+```bash
+claude mcp add --transport stdio project-atlas -- project-atlas-mcp
+```
+
+Cursor 项目配置：
+
+```json
+{
+  "mcpServers": {
+    "project-atlas": {
+      "type": "stdio",
+      "command": "project-atlas-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Continue 配置：
+
+```yaml
+mcpServers:
+  - name: project-atlas
+    command: project-atlas-mcp
+    args: []
+```
+
+更多说明见 `adapters/claude-code/`、`adapters/cursor/` 和 `adapters/continue/`。
+
+## 发布前检查
+
+发布前固定执行：
+
+```bash
+npm run lint:types
+npm test
+npm pack --dry-run
+npm run verify
+node dist/index.js --help
+node dist/index.js init --help
+node dist/index.js context --help
+node dist/index.js propose --help
+node dist/index.js remember --help
+node dist/index.js check --help
+node dist/mcp.js --help
+```
+
+`npm run verify` 会执行类型检查和测试。`npm test` 会先构建再运行测试。`npm run pack:dry-run` 是打包预检的快捷脚本。
+
+`npm pack --dry-run` 应包含 `README.md`、`LICENSE`、`CHANGELOG.md`、`dist/`、`adapters/`、`schema/`、`templates/`、`docs/site/` 和 `package.json`。
+
+## 如果现在要发布
+
+当前包名 `project-atlas` 在 npm registry 未被占用，可以按首次发布处理。详细步骤见 [docs/site/publish-now.md](docs/site/publish-now.md)。
+
+最短命令顺序：
+
+```bash
+git status --branch --short
+npm run verify
+npm pack --dry-run
+npm login
+npm whoami
+npm publish
+git tag v0.1.0
+git push origin main --tags
+```
+
+发布前要先确认 `CHANGELOG.md` 已经把本次要发布的内容归入目标版本，并确认本地 `main` 已推送到 `origin/main`。如果 GitHub 仓库也要同步改名，需要先把远端仓库改成 `project-atlas`，再确认 `package.json` 的 repository URL 可访问。
+
+## 第一版边界
+
+- 只支持 Git 仓库。
+- 不做 Web UI。
+- 只提供本地 stdio MCP server，不提供远程 HTTP MCP server。
+- 不内置语义检索或代码图谱。
+- 不提供模型可调用的 apply 工具。
+- 不提供个人长期记忆库。
+- OpenCode、Claude Code、Cursor 和 Continue 支持都是 adapter 示例，不是核心产品。

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported Versions
+
+Project Atlas is pre-1.0. Security fixes target the latest published version and the `main` branch.
+
+## Reporting A Vulnerability
+
+Please report security issues through GitHub private vulnerability reporting if it is enabled for this repository.
+
+If private vulnerability reporting is not enabled, open a minimal GitHub issue that does not include exploit details, credentials, proprietary code, or private project data.
+
+## Security Boundaries
+
+Project Atlas is designed around these boundaries:
+
+- Agents may read context.
+- Agents may create proposals.
+- Agents must not apply proposals.
+- MCP and adapter integrations must not expose an apply tool.
+- `project-atlas apply` requires human terminal confirmation.
+- Local proposal evidence under `.project-atlas/` should not be committed.
+
+## Sensitive Data
+
+Project Atlas can scan project files and generate knowledge proposals. Users should review generated proposal content before applying it.
+
+Do not store secrets in `knowledge/`. If sensitive data is detected in a proposal, reject the proposal and replace it with a redacted summary.

package/adapters/claude-code/README.md

@@ -0,0 +1,27 @@
+# Claude Code Adapter
+
+Claude Code can connect to `project-atlas-mcp` as a local stdio MCP server.
+
+Install `project-atlas` first, then add the server from a project directory:
+
+```bash
+claude mcp add --transport stdio project-atlas -- project-atlas-mcp
+```
+
+For a team-shared project config, create `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "project-atlas": {
+      "type": "stdio",
+      "command": "project-atlas-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Available tools are scan, context, stale, propose, remember, check, and review summary.
+
+No model-callable write tool is provided. A human must do terminal apply after reviewing proposal evidence.

package/adapters/continue/README.md

@@ -0,0 +1,16 @@
+# Continue Adapter
+
+Continue can use `project-atlas-mcp` through its MCP context provider support.
+
+Add this to `config.yaml`:
+
+```yaml
+mcpServers:
+  - name: project-atlas
+    command: project-atlas-mcp
+    args: []
+```
+
+After reloading Continue, choose the MCP context provider and call the safe project-atlas tools for scan, context, stale checks, proposals, project memory proposals, health checks, and review summary.
+
+The adapter does not provide a direct write tool. A human must do terminal apply after proposal review.

package/adapters/cursor/README.md

@@ -0,0 +1,29 @@
+# Cursor Adapter
+
+Cursor can load `project-atlas-mcp` through project or global MCP config.
+
+For project-scoped use, create `.cursor/mcp.json` in the target repository:
+
+```json
+{
+  "mcpServers": {
+    "project-atlas": {
+      "type": "stdio",
+      "command": "project-atlas-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Use the MCP tool list in Cursor to confirm these tools are available:
+
+- `project_atlas_scan`
+- `project_atlas_context`
+- `project_atlas_stale`
+- `project_atlas_propose`
+- `project_atlas_remember`
+- `project_atlas_check`
+- `project_atlas_review_summary`
+
+The adapter only exposes read and proposal evidence actions. A human must do terminal apply after checking the review summary.

package/adapters/opencode/README.md

@@ -0,0 +1,37 @@
+# OpenCode Adapter Example
+
+This adapter shows how OpenCode can call `project-atlas` without making OpenCode the core product.
+
+## Install
+
+1. Install and build `project-atlas`.
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+2. Copy this folder into the matching OpenCode assets location used by your team.
+
+```text
+adapters/opencode/tools
+adapters/opencode/commands
+adapters/opencode/skills
+```
+
+3. Restart OpenCode so it reloads the tools, commands, and skill.
+
+The tools only call read, scan, and proposal commands. There is no apply tool. Real writes must be done by a human in a terminal:
+
+```bash
+project-atlas apply --repo <repo> --proposal-id <id> --confirm
+```
+
+## Manual Smoke Test
+
+- Run `project_atlas_scan` in a temporary Git project and confirm it returns scan JSON.
+- Run `project_atlas_context` with a small query and confirm it returns source paths.
+- Run `project_atlas_propose` with one target under `knowledge/` and confirm it creates proposal evidence.
+- Confirm no `project_atlas_apply` tool exists.
+- Confirm the proposal output tells the user to run `project-atlas apply` in a terminal.

package/adapters/opencode/commands/kb-context.md

@@ -0,0 +1,5 @@
+---
+description: Read project-atlas context pack
+---
+
+Call `project_atlas_context` with the current task topic. Use the returned source paths when citing project knowledge.

package/adapters/opencode/commands/kb-refresh.md

@@ -0,0 +1,11 @@
+---
+description: Generate project-atlas update proposal
+---
+
+Call `project_atlas_scan` with `mode=changed`. If the scan shows stable project knowledge changed, create a proposal through `project_atlas_propose`.
+
+Do not apply the proposal from OpenCode. Tell the user to run:
+
+```bash
+project-atlas apply --repo <repo> --proposal-id <id> --confirm
+```

package/adapters/opencode/skills/project-atlas/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: project-knowledge-base
+description: Use when reading, checking, or proposing updates to a project-atlas knowledge base.
+---
+
+Use `project-atlas` as the source of truth for project knowledge governance.
+
+Rules:
+
+- Read context with `project-atlas context` or the OpenCode `project_atlas_context` tool.
+- Generate evidence with `project-atlas scan`, `project-atlas stale`, and `project-atlas review-summary`.
+- Generate proposals with `project-atlas propose` or the OpenCode `project_atlas_propose` tool.
+- Never apply knowledge changes from an agent tool.
+- Real writes require a human terminal command with TTY confirmation.
+- Do not write secrets, tokens, passwords, or access keys into knowledge files.

package/adapters/opencode/tools/project_atlas_context.js

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+import { tool } from "@opencode-ai/plugin";
+
+function run(command, args, cwd, abort) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, shell: false, env: process.env });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    abort?.addEventListener("abort", () => child.kill("SIGTERM"), { once: true });
+    child.on("error", (error) => resolve({ stdout, stderr: `${stderr}${error.message}`, exitCode: 127 }));
+    child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 1 }));
+  });
+}
+
+export default tool({
+  description: "Read a compact project-atlas context pack. This tool never writes knowledge files.",
+  args: {
+    query: tool.schema.string().optional().describe("Optional topic or keyword"),
+    budget: tool.schema.number().optional().describe("Maximum context characters"),
+  },
+  async execute(args, context) {
+    const repo = context.worktree || context.directory || process.cwd();
+    const commandArgs = ["context", "--repo", repo, "--budget", String(args.budget || 8000)];
+    if (args.query) commandArgs.push("--query", args.query);
+    const result = await run("project-atlas", commandArgs, repo, context.abort);
+    return {
+      output: result.stdout || result.stderr,
+      metadata: { repo, exitCode: result.exitCode },
+    };
+  },
+});

package/adapters/opencode/tools/project_atlas_propose.js

@@ -0,0 +1,53 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { tool } from "@opencode-ai/plugin";
+
+function run(command, args, cwd, abort) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, shell: false, env: process.env });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    abort?.addEventListener("abort", () => child.kill("SIGTERM"), { once: true });
+    child.on("error", (error) => resolve({ stdout, stderr: `${stderr}${error.message}`, exitCode: 127 }));
+    child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 1 }));
+  });
+}
+
+export default tool({
+  description: "Create a project-atlas proposal. This tool never applies knowledge changes.",
+  args: {
+    reason: tool.schema.string().describe("Why knowledge should be updated"),
+    updates: tool.schema
+      .array(
+        tool.schema.object({
+          target: tool.schema.string().describe("Target path under knowledge/"),
+          content: tool.schema.string().describe("Markdown content"),
+        }),
+      )
+      .describe("Knowledge updates to propose"),
+    sourceFiles: tool.schema.array(tool.schema.string()).optional().describe("Source evidence files"),
+  },
+  async execute(args, context) {
+    const repo = context.worktree || context.directory || process.cwd();
+    const dir = await mkdtemp(path.join(tmpdir(), "project-atlas-opencode-"));
+    const updatesFile = path.join(dir, "updates.json");
+    await writeFile(updatesFile, JSON.stringify({ source_files: args.sourceFiles || [], updates: args.updates }, null, 2), "utf8");
+    try {
+      const result = await run("project-atlas", ["propose", "--repo", repo, "--updates-file", updatesFile, "--reason", args.reason], repo, context.abort);
+      return {
+        output: `${result.stdout || result.stderr}\n\nNo apply tool is available. A human must run project-atlas apply in a terminal.`,
+        metadata: { repo, exitCode: result.exitCode },
+      };
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  },
+});