project-atlas 0.1.0

package/docs/site/agent-quickstart.md

@@ -0,0 +1,243 @@
+# Agent Quickstart
+
+This document is for AI coding agents. Its purpose is to make Project Atlas usable in the first 60 seconds of a task.
+
+Agents should read governed project knowledge before broad source exploration, check whether the knowledge base is healthy, and create reviewable proposals when durable knowledge should change.
+
+## Rules
+
+- Read Project Atlas before broad source exploration.
+- Default to read-only commands.
+- You may run `context`, `check`, `scan`, `stale`, and `review-summary`.
+- You may run `propose` and `remember` to create proposals.
+- Do not run `project-atlas apply`.
+- Do not configure `project-atlas apply` as an MCP tool, agent tool, hook, or automatic script.
+- If `knowledge/manifest.json` is missing, do not silently initialize the repository. Tell the user and provide the init command.
+- When answering, list the knowledge files used, commands run, and anything that still needs human review.
+
+## First Probe
+
+Run from the repository root:
+
+```bash
+command -v project-atlas
+project-atlas --help
+test -f knowledge/manifest.json && echo "project-atlas: initialized" || echo "project-atlas: missing manifest"
+```
+
+If the command is missing:
+
+```bash
+npm install -g project-atlas
+```
+
+If the repository is not initialized, ask the user before running:
+
+```bash
+project-atlas init --repo "$PWD" --template generic-service
+```
+
+Use `java-backend` for Java backend repositories:
+
+```bash
+project-atlas init --repo "$PWD" --template java-backend
+```
+
+Use `frontend-app` for frontend repositories:
+
+```bash
+project-atlas init --repo "$PWD" --template frontend-app
+```
+
+## Read Context Before The Task
+
+Use the task title, requirement keywords, or module names mentioned by the user:
+
+```bash
+project-atlas context --repo "$PWD" --query "<task keywords>" --budget 8000 --format json
+```
+
+If the user mentions a specific file, look up knowledge by source file:
+
+```bash
+project-atlas context --repo "$PWD" --source-file "<repo-relative-file>" --format json
+```
+
+If the task depends on project memory metadata, filter by memory metadata:
+
+```bash
+project-atlas context --repo "$PWD" --memory-type decision --topic "<topic>" --scope "<scope>" --format json
+```
+
+When reading JSON output, inspect:
+
+- `items[].source_path`
+- `items[].source_type`
+- `items[].metadata`
+- `truncated`
+- `budget_used`
+
+If `truncated` is `true`, narrow `--query` or raise `--budget`, then read context again.
+
+## Health Check
+
+Before creating a proposal, handing off work, or preparing a release, run:
+
+```bash
+project-atlas check --repo "$PWD" --format json
+```
+
+If the result reports missing sources, stale sources, missing metadata, bad links, or duplicate topics, mention the risk in your answer. Do not treat unhealthy knowledge as fully trusted.
+
+## Create A Knowledge Proposal
+
+When the task produces durable project knowledge, prepare `updates.json`:
+
+```json
+{
+  "source_files": ["README.md"],
+  "updates": [
+    {
+      "target": "knowledge/project/overview.md",
+      "content": "# Project Overview\n\nWrite verified project knowledge here.\n"
+    }
+  ]
+}
+```
+
+Create the proposal:
+
+```bash
+project-atlas propose --repo "$PWD" --updates-file updates.json --reason "<why this knowledge changed>"
+```
+
+If the target knowledge document already has source metadata and the user explicitly wants to inherit it, run:
+
+```bash
+project-atlas propose --repo "$PWD" --updates-file updates.json --reason "<why this knowledge changed>" --inherit-source-metadata
+```
+
+## Create A Project Memory Proposal
+
+When the task produces a durable decision, experience, or project fact, prepare `memory.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "source_files": ["docs/development-log/example.md"],
+  "memories": [
+    {
+      "target": "knowledge/decisions/example.md",
+      "memory_type": "decision",
+      "topic": "example decision",
+      "scope": "backend",
+      "confidence": 0.9,
+      "summary": "Short stable memory summary.",
+      "body": "Detailed memory body with source evidence."
+    }
+  ]
+}
+```
+
+Create the memory proposal:
+
+```bash
+project-atlas remember --repo "$PWD" --candidate-file memory.json --reason "<why this memory matters>"
+```
+
+Allowed memory types:
+
+- `decision`
+- `experience`
+- `project_fact`
+
+## Review Summary
+
+After creating a proposal, read the review summary:
+
+```bash
+project-atlas review-summary --repo "$PWD"
+```
+
+Report:
+
+- proposal id
+- target files
+- source files
+- dry-run summary
+- review decision
+- apply safety
+- whether human terminal apply is required
+
+## MCP Tools
+
+When connected through `project-atlas-mcp`, use only these tools:
+
+- `project_atlas_scan`
+- `project_atlas_context`
+- `project_atlas_stale`
+- `project_atlas_propose`
+- `project_atlas_remember`
+- `project_atlas_check`
+- `project_atlas_review_summary`
+
+There is no apply tool. If an MCP tool creates a proposal, tell the user to review it and apply it manually in a terminal.
+
+## MCP Client Config
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio project-atlas -- project-atlas-mcp
+```
+
+Cursor project config `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "project-atlas": {
+      "type": "stdio",
+      "command": "project-atlas-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Continue config:
+
+```yaml
+mcpServers:
+  - name: project-atlas
+    command: project-atlas-mcp
+    args: []
+```
+
+## AGENTS.md Snippet
+
+```md
+Before changing code, run Project Atlas context for the current task:
+
+project-atlas context --repo "$PWD" --query "<task keywords>" --budget 8000 --format json
+
+If a file is mentioned, also run:
+
+project-atlas context --repo "$PWD" --source-file "<repo-relative-file>" --format json
+
+Use Project Atlas outputs as governed project knowledge. You may run check, scan, stale, propose, remember, and review-summary. Do not run project-atlas apply. If knowledge should be updated, create a proposal and tell the user to review and apply it manually in a terminal.
+```
+
+## Agent Response Template
+
+```text
+Project Atlas:
+- commands run:
+- knowledge files used:
+- stale or health issues:
+- proposal id, if created:
+- apply status: human terminal apply required or not needed
+
+Task answer:
+- ...
+```

package/docs/site/best-practices.md

@@ -0,0 +1,87 @@
+# Project Atlas 最佳实践
+
+Project Atlas 适合沉淀稳定、可验证、会被多次复用的项目知识。它不适合自动生成整仓长文档。
+
+## 写什么
+
+- 项目定位和模块边界。
+- 业务术语和页面、接口、任务的真实含义。
+- 稳定流程，比如订单、支付、审核、同步。
+- 对外契约，比如 API、MQ、文件、配置。
+- 风险点，比如敏感配置、人工操作、迁移约束。
+- 已经确认的技术或业务决策。
+- 可复用项目记忆，比如稳定事实、已做决策和踩坑经验。
+
+## 不写什么
+
+- 临时调试过程。
+- 未验证的猜测。
+- 大段源码复制。
+- 过期设计稿。
+- 密钥、token、密码和真实敏感配置值。
+
+## 来源文件
+
+每篇知识文档都应该能追溯到来源文件。建议优先引用：
+
+- README 和需求文档。
+- OpenSpec 规格。
+- 关键源码入口。
+- 配置样例。
+- 已确认的开发日志。
+
+`source_files` 和 `source_hashes` 可以让 stale 检测发现知识是否过期。
+
+## 项目记忆
+
+项目记忆适合写三类内容：
+
+- `decision` 记录已经确认的决策，适合后续任务直接遵守。
+- `experience` 记录完成过的工作经验，适合避免重复试错。
+- `project_fact` 记录稳定项目事实，适合新任务快速理解背景。
+
+记忆内容必须有来源。来源可以是 README、开发日志、OpenSpec、关键代码入口或 review 结论。不要把个人偏好、未验证猜测和聊天原文写成项目记忆。
+
+建议把记忆目标放在合适目录：
+
+- 决策放 `knowledge/decisions/`。
+- 业务事实放 `knowledge/domains/` 或 `knowledge/project/`。
+- 经验放最接近的业务或质量目录。
+
+生成记忆 proposal：
+
+```bash
+project-atlas remember --repo /path/to/repo --candidate-file memory.json --reason "capture stable project memory"
+```
+
+默认不会覆盖已有目标文件。确实要替换时，显式加 `--replace-existing`，并在 review 中说明原因。
+
+## 更新节奏
+
+- 小改动只在需要时更新相关知识。
+- 跨模块需求完成后，运行 `scan` 和 `stale`。
+- 由 agent 生成 proposal，由人 review 后再 apply。
+- 每次发布前确认 `review-summary` 没有敏感阻断。
+- 发布前或交接前运行 `project-atlas check`，确认知识库健康。
+
+## Agent 使用建议
+
+Agent 开始任务前先读：
+
+```bash
+project-atlas context --repo /path/to/repo --query "<task topic>"
+```
+
+任务结束后，如果稳定知识发生变化，再生成 proposal：
+
+```bash
+project-atlas propose --repo /path/to/repo --updates-file updates.json --reason "refresh project knowledge"
+```
+
+如果任务沉淀的是项目记忆，使用：
+
+```bash
+project-atlas remember --repo /path/to/repo --candidate-file memory.json --reason "capture task memory"
+```
+
+Project Atlas 的重点是让团队少重复解释项目背景，同时保留人工把关。

package/docs/site/en/README.md

@@ -0,0 +1,49 @@
+# Project Atlas Documentation
+
+Project Atlas is a Git-first project knowledge base CLI for engineering teams and AI coding agents.
+
+The npm package is `project-atlas`. The CLI command is `project-atlas`. The local stdio MCP server is `project-atlas-mcp`.
+
+## Start Here
+
+If you are an AI agent, read [Agent Quickstart](agent-quickstart.md) first. It is written as an execution protocol, not as a long tutorial.
+
+If you are setting up the tool manually, read [Quick Start](quick-start.md).
+
+Chinese documentation is available at [../README.md](../README.md).
+
+## Core Boundary
+
+Project Atlas stores shared project knowledge under `knowledge/` and local proposal evidence under `.project-atlas/proposals/`.
+
+Agents may read context and create proposals. Agents must not apply proposals. Real writes still require a human terminal confirmation through:
+
+```bash
+project-atlas apply --repo /path/to/repo --proposal-id <id> --confirm
+```
+
+## Common Commands
+
+```bash
+project-atlas init --repo /path/to/repo --template generic-service
+project-atlas context --repo /path/to/repo --query "order payment" --budget 8000 --format json
+project-atlas check --repo /path/to/repo --format json
+project-atlas propose --repo /path/to/repo --updates-file updates.json --reason "refresh knowledge"
+project-atlas remember --repo /path/to/repo --candidate-file memory.json --reason "capture project memory"
+project-atlas review-summary --repo /path/to/repo
+project-atlas-mcp --help
+```
+
+## MCP Tools
+
+The MCP server exposes only safe tools:
+
+- `project_atlas_scan`
+- `project_atlas_context`
+- `project_atlas_stale`
+- `project_atlas_propose`
+- `project_atlas_remember`
+- `project_atlas_check`
+- `project_atlas_review_summary`
+
+No MCP apply tool exists.

package/docs/site/en/agent-quickstart.md

@@ -0,0 +1,191 @@
+# Agent Quickstart
+
+This document is for AI coding agents. The goal is to read governed project knowledge in the first 60 seconds of a task, check whether the knowledge base is healthy, and create reviewable proposals when knowledge should change.
+
+## Rules
+
+- Read Project Atlas before broad source exploration.
+- Default to read-only commands.
+- You may run `context`, `check`, `scan`, `stale`, and `review-summary`.
+- You may run `propose` and `remember` to create proposals.
+- Do not run `project-atlas apply`.
+- Do not configure `project-atlas apply` as an MCP tool, agent tool, or automatic script.
+- If `knowledge/manifest.json` is missing, do not silently initialize the repo. Tell the user and provide the init command.
+- When answering, list the knowledge files used, commands run, and any issue that still needs human review.
+
+## First Probe
+
+Run from the repository root:
+
+```bash
+command -v project-atlas
+project-atlas --help
+test -f knowledge/manifest.json && echo "project-atlas: initialized" || echo "project-atlas: missing manifest"
+```
+
+If the command is missing:
+
+```bash
+npm install -g project-atlas
+```
+
+If the repo is not initialized, ask the user before running:
+
+```bash
+project-atlas init --repo "$PWD" --template generic-service
+```
+
+Use `java-backend` for Java backend repos and `frontend-app` for frontend repos.
+
+## Read Context
+
+Use task keywords:
+
+```bash
+project-atlas context --repo "$PWD" --query "<task keywords>" --budget 8000 --format json
+```
+
+If a file is mentioned:
+
+```bash
+project-atlas context --repo "$PWD" --source-file "<repo-relative-file>" --format json
+```
+
+If project memory metadata matters:
+
+```bash
+project-atlas context --repo "$PWD" --memory-type decision --topic "<topic>" --scope "<scope>" --format json
+```
+
+Check `items[].source_path`, `items[].source_type`, `items[].metadata`, `truncated`, and `budget_used`.
+
+## Health Check
+
+Before proposing knowledge changes or handing off work:
+
+```bash
+project-atlas check --repo "$PWD" --format json
+```
+
+Report missing sources, stale sources, missing metadata, bad links, and duplicate topics. Do not treat unhealthy knowledge as fully trusted.
+
+## Create A Knowledge Proposal
+
+Prepare `updates.json`:
+
+```json
+{
+  "source_files": ["README.md"],
+  "updates": [
+    {
+      "target": "knowledge/project/overview.md",
+      "content": "# Project Overview\n\nWrite verified project knowledge here.\n"
+    }
+  ]
+}
+```
+
+Create the proposal:
+
+```bash
+project-atlas propose --repo "$PWD" --updates-file updates.json --reason "<why this knowledge changed>"
+```
+
+## Create A Project Memory Proposal
+
+Prepare `memory.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "source_files": ["docs/development-log/example.md"],
+  "memories": [
+    {
+      "target": "knowledge/decisions/example.md",
+      "memory_type": "decision",
+      "topic": "example decision",
+      "scope": "backend",
+      "confidence": 0.9,
+      "summary": "Short stable memory summary.",
+      "body": "Detailed memory body with source evidence."
+    }
+  ]
+}
+```
+
+Run:
+
+```bash
+project-atlas remember --repo "$PWD" --candidate-file memory.json --reason "<why this memory matters>"
+```
+
+Allowed memory types are `decision`, `experience`, and `project_fact`.
+
+## Review Summary
+
+After creating a proposal:
+
+```bash
+project-atlas review-summary --repo "$PWD"
+```
+
+Report the proposal id, target files, source files, dry-run summary, review decision, apply safety, and whether human apply is needed.
+
+## MCP
+
+Use only these MCP tools:
+
+- `project_atlas_scan`
+- `project_atlas_context`
+- `project_atlas_stale`
+- `project_atlas_propose`
+- `project_atlas_remember`
+- `project_atlas_check`
+- `project_atlas_review_summary`
+
+There is no apply tool.
+
+## MCP Client Config
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio project-atlas -- project-atlas-mcp
+```
+
+Cursor project config `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "project-atlas": {
+      "type": "stdio",
+      "command": "project-atlas-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Continue config:
+
+```yaml
+mcpServers:
+  - name: project-atlas
+    command: project-atlas-mcp
+    args: []
+```
+
+## Agent Response Template
+
+```text
+Project Atlas:
+- commands run:
+- knowledge files used:
+- stale or health issues:
+- proposal id, if created:
+- apply status: human terminal apply required or not needed
+
+Task answer:
+- ...
+```

package/docs/site/en/quick-start.md

@@ -0,0 +1,79 @@
+# Quick Start
+
+This page is the shortest manual path for trying Project Atlas.
+
+## Install Or Build
+
+From this repository:
+
+```bash
+npm install
+npm run build
+```
+
+After npm publish, users can install:
+
+```bash
+npm install -g project-atlas
+project-atlas --help
+```
+
+## Initialize A Repository
+
+```bash
+project-atlas init --repo /path/to/repo --template generic-service
+```
+
+Available templates:
+
+- `generic-service`
+- `java-backend`
+- `frontend-app`
+
+## Read Context
+
+```bash
+project-atlas context --repo /path/to/repo --query "order payment" --budget 8000 --format json
+```
+
+Lookup knowledge by source file:
+
+```bash
+project-atlas context --repo /path/to/repo --source-file README.md --format json
+```
+
+## Create A Proposal
+
+Prepare `updates.json`:
+
+```json
+{
+  "source_files": ["README.md"],
+  "updates": [
+    {
+      "target": "knowledge/project/overview.md",
+      "content": "# Project Overview\n\nWrite verified project knowledge here.\n"
+    }
+  ]
+}
+```
+
+Run:
+
+```bash
+project-atlas propose --repo /path/to/repo --updates-file updates.json --reason "refresh overview"
+```
+
+## Review And Apply
+
+```bash
+project-atlas review-summary --repo /path/to/repo
+```
+
+Only a human should apply:
+
+```bash
+project-atlas apply --repo /path/to/repo --proposal-id <id> --confirm
+```
+
+Agents must not run apply.