project-atlas 0.1.0

package/dist/frontmatter.js

@@ -0,0 +1,103 @@
+export function parseFrontmatter(content) {
+    if (!content.startsWith("---\n")) {
+        return { metadata: null, body: content };
+    }
+    const end = content.indexOf("\n---", 4);
+    if (end < 0) {
+        return { metadata: null, body: content };
+    }
+    const raw = content.slice(4, end).split(/\r?\n/);
+    const body = content.slice(end + 4).replace(/^\r?\n/, "");
+    const metadata = { source_files: [], source_hashes: {} };
+    let section = "";
+    for (const line of raw) {
+        if (!line.trim()) {
+            continue;
+        }
+        if (/^[A-Za-z0-9_]+:\s*$/.test(line)) {
+            const key = line.replace(":", "").trim();
+            section = key === "source_files" || key === "source_hashes" || key === "related_docs" ? key : "";
+            continue;
+        }
+        if ((section === "source_files" || section === "related_docs") && line.trim().startsWith("- ")) {
+            const item = line.trim().slice(2).trim();
+            if (section === "source_files")
+                metadata.source_files.push(item);
+            if (section === "related_docs")
+                metadata.related_docs = [...(metadata.related_docs ?? []), item];
+            continue;
+        }
+        if (section === "source_hashes" && line.startsWith("  ")) {
+            const index = line.indexOf(":");
+            if (index > 0) {
+                metadata.source_hashes[line.slice(0, index).trim()] = line.slice(index + 1).trim();
+            }
+            continue;
+        }
+        const index = line.indexOf(":");
+        if (index > 0) {
+            const key = line.slice(0, index).trim();
+            const value = line.slice(index + 1).trim();
+            section = "";
+            if (key === "kb_schema")
+                metadata.kb_schema = value;
+            if (key === "generated_by")
+                metadata.generated_by = value;
+            if (key === "review_status")
+                metadata.review_status = value;
+            if (key === "memory_type" && isMemoryType(value))
+                metadata.memory_type = value;
+            if (key === "topic")
+                metadata.topic = value;
+            if (key === "scope")
+                metadata.scope = value;
+            if (key === "confidence") {
+                const confidence = Number(value);
+                if (Number.isFinite(confidence))
+                    metadata.confidence = confidence;
+            }
+            if (key === "owner")
+                metadata.owner = value;
+        }
+    }
+    return { metadata, body };
+}
+export function buildFrontmatter(metadata) {
+    const lines = ["---", `kb_schema: ${metadata.kb_schema ?? "1"}`, "source_files:"];
+    for (const source of metadata.source_files) {
+        lines.push(`  - ${source}`);
+    }
+    lines.push("source_hashes:");
+    for (const [source, hash] of Object.entries(metadata.source_hashes)) {
+        lines.push(`  ${source}: ${hash}`);
+    }
+    lines.push(`generated_by: ${metadata.generated_by ?? "project-atlas"}`);
+    lines.push(`review_status: ${metadata.review_status ?? "draft"}`);
+    if (metadata.memory_type)
+        lines.push(`memory_type: ${metadata.memory_type}`);
+    if (metadata.topic)
+        lines.push(`topic: ${metadata.topic}`);
+    if (metadata.scope)
+        lines.push(`scope: ${metadata.scope}`);
+    if (metadata.confidence !== undefined)
+        lines.push(`confidence: ${metadata.confidence}`);
+    if (metadata.owner)
+        lines.push(`owner: ${metadata.owner}`);
+    if (metadata.related_docs?.length) {
+        lines.push("related_docs:");
+        for (const doc of metadata.related_docs) {
+            lines.push(`  - ${doc}`);
+        }
+    }
+    lines.push("---", "");
+    return lines.join("\n");
+}
+export function ensureKnowledgeFrontmatter(content, metadata) {
+    if (content.startsWith("---\n")) {
+        return content;
+    }
+    return `${buildFrontmatter(metadata)}${content}`;
+}
+function isMemoryType(value) {
+    return value === "decision" || value === "experience" || value === "project_fact";
+}

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "./core.js";
+runCli(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/dist/mcp.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+import { runCliCapture } from "./core.js";
+const help = [
+    "Usage: project-atlas-mcp",
+    "",
+    "Starts the local stdio MCP server for project-atlas.",
+    "",
+    "Tools:",
+    "  project_atlas_scan",
+    "  project_atlas_context",
+    "  project_atlas_stale",
+    "  project_atlas_propose",
+    "  project_atlas_remember",
+    "  project_atlas_check",
+    "  project_atlas_review_summary",
+    "",
+    "No apply tool is exposed. A human must run project-atlas apply in a terminal.",
+].join("\n");
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(help);
+    process.exit(0);
+}
+const server = new McpServer({
+    name: "project-atlas",
+    version: "0.1.0",
+});
+server.registerTool("project_atlas_scan", {
+    title: "Project Atlas Scan",
+    description: "Scan project shape and optional external code evidence. This tool does not write knowledge files.",
+    inputSchema: z.object({
+        repo: z.string().optional().describe("Git repository path. Defaults to the MCP server working directory."),
+        mode: z.enum(["full", "changed"]).optional().describe("Scan mode. Defaults to full."),
+        external_evidence_file: z.string().optional().describe("JSON file with external repo map or code graph evidence."),
+    }),
+}, async ({ repo, mode, external_evidence_file }) => cliTool([
+    "scan",
+    "--repo",
+    repo || process.cwd(),
+    "--mode",
+    mode || "full",
+    ...flag("external-evidence-file", external_evidence_file),
+]));
+server.registerTool("project_atlas_context", {
+    title: "Project Atlas Context",
+    description: "Read a compact project-atlas context pack. This tool never writes files.",
+    inputSchema: z.object({
+        repo: z.string().optional().describe("Git repository path. Defaults to the MCP server working directory."),
+        query: z.string().optional().describe("One or more keywords. Any keyword may match."),
+        source_file: z.string().optional().describe("Return knowledge docs whose source_files include this path."),
+        memory_type: z.enum(["decision", "experience", "project_fact"]).optional().describe("Filter project memory type."),
+        topic: z.string().optional().describe("Filter project memories by topic substring."),
+        scope: z.string().optional().describe("Filter project memories by scope substring."),
+        budget: z.number().int().positive().optional().describe("Maximum context characters. Defaults to 8000."),
+        format: z.enum(["markdown", "json"]).optional().describe("Output format. Defaults to markdown."),
+    }),
+}, async ({ repo, query, source_file, memory_type, topic, scope, budget, format }) => cliTool([
+    "context",
+    "--repo",
+    repo || process.cwd(),
+    ...flag("query", query),
+    ...flag("source-file", source_file),
+    ...flag("memory-type", memory_type),
+    ...flag("topic", topic),
+    ...flag("scope", scope),
+    ...flag("budget", budget),
+    ...flag("format", format),
+]));
+server.registerTool("project_atlas_stale", {
+    title: "Project Atlas Stale",
+    description: "Check knowledge docs against source file hashes. This tool never writes files.",
+    inputSchema: z.object({
+        repo: z.string().optional().describe("Git repository path. Defaults to the MCP server working directory."),
+        format: z.enum(["markdown", "json"]).optional().describe("Output format. Defaults to markdown."),
+    }),
+}, async ({ repo, format }) => cliTool(["stale", "--repo", repo || process.cwd(), ...flag("format", format)]));
+server.registerTool("project_atlas_propose", {
+    title: "Project Atlas Propose",
+    description: "Create reviewable knowledge update evidence. This tool cannot apply the proposal.",
+    inputSchema: z.object({
+        repo: z.string().optional().describe("Git repository path. Defaults to the MCP server working directory."),
+        updates_file: z.string().optional().describe("JSON file with source_files, external_evidence, and updates."),
+        target: z.string().optional().describe("Single target under knowledge/**."),
+        content_file: z.string().optional().describe("Markdown content for a single target."),
+        external_evidence_file: z.string().optional().describe("JSON file with external repo map or code graph evidence."),
+        reason: z.string().optional().describe("Human-readable proposal reason."),
+        inherit_source_metadata: z.boolean().optional().describe("Merge existing target source_files into the proposal."),
+    }),
+}, async ({ repo, updates_file, target, content_file, external_evidence_file, reason, inherit_source_metadata }) => {
+    const output = await cliTool([
+        "propose",
+        "--repo",
+        repo || process.cwd(),
+        ...flag("updates-file", updates_file),
+        ...flag("target", target),
+        ...flag("content-file", content_file),
+        ...flag("external-evidence-file", external_evidence_file),
+        ...flag("reason", reason),
+        ...(inherit_source_metadata ? ["--inherit-source-metadata"] : []),
+    ]);
+    return appendText(output, "\nNo apply tool is available. A human must run project-atlas apply in a terminal.");
+});
+server.registerTool("project_atlas_remember", {
+    title: "Project Atlas Remember",
+    description: "Create reviewable project memory update evidence. This tool cannot apply the proposal.",
+    inputSchema: z.object({
+        repo: z.string().optional().describe("Git repository path. Defaults to the MCP server working directory."),
+        candidate_file: z.string().describe("JSON memory candidate file."),
+        reason: z.string().describe("Human-readable proposal reason."),
+        format: z.enum(["markdown", "json"]).optional().describe("Output format. Defaults to markdown."),
+        replace_existing: z.boolean().optional().describe("Allow proposal generation for existing target files."),
+    }),
+}, async ({ repo, candidate_file, reason, format, replace_existing }) => {
+    const output = await cliTool([
+        "remember",
+        "--repo",
+        repo || process.cwd(),
+        "--candidate-file",
+        candidate_file,
+        "--reason",
+        reason,
+        ...flag("format", format),
+        ...(replace_existing ? ["--replace-existing"] : []),
+    ]);
+    return appendText(output, "\nNo apply tool is available. A human must run project-atlas apply in a terminal.");
+});
+server.registerTool("project_atlas_check", {
+    title: "Project Atlas Check",
+    description: "Check project knowledge health. This tool never writes files.",
+    inputSchema: z.object({
+        repo: z.string().optional().describe("Git repository path. Defaults to the MCP server working directory."),
+        format: z.enum(["markdown", "json"]).optional().describe("Output format. Defaults to markdown."),
+    }),
+}, async ({ repo, format }) => cliTool(["check", "--repo", repo || process.cwd(), ...flag("format", format)]));
+server.registerTool("project_atlas_review_summary", {
+    title: "Project Atlas Review Summary",
+    description: "Print reviewer-friendly proposal evidence. This tool never applies proposals.",
+    inputSchema: z.object({
+        repo: z.string().optional().describe("Git repository path. Defaults to the MCP server working directory."),
+        proposal_id: z.string().optional().describe("Proposal id. Defaults to latest.json."),
+    }),
+}, async ({ repo, proposal_id }) => cliTool(["review-summary", "--repo", repo || process.cwd(), ...flag("proposal-id", proposal_id)]));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+let cliQueue = Promise.resolve();
+async function cliTool(args) {
+    const run = async () => {
+        try {
+            return { content: [{ type: "text", text: await runCliCapture(args) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { isError: true, content: [{ type: "text", text: message }] };
+        }
+    };
+    const result = cliQueue.then(run, run);
+    cliQueue = result.then(() => undefined, () => undefined);
+    return result;
+}
+function appendText(result, text) {
+    return {
+        ...result,
+        content: result.content.map((item, index) => (index === 0 ? { ...item, text: `${item.text}${text}` } : item)),
+    };
+}
+function flag(name, value) {
+    if (value === undefined || value === "") {
+        return [];
+    }
+    return [`--${name}`, String(value)];
+}

package/dist/scanner.js

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { changedFiles, currentCommit, runGit, walkFiles, worktreeHash } from "./utils.js";
+export function scanRepo(repo, mode, externalEvidence = []) {
+    const allFiles = walkFiles(repo);
+    const scopedFiles = mode === "changed" ? changedFiles(repo) : allFiles;
+    const entries = {
+        controller: [],
+        service: [],
+        feign: [],
+        tasks: [],
+        mq: [],
+        remote: [],
+        config: [],
+    };
+    for (const rel of scopedFiles) {
+        const type = entryType(rel);
+        if (type) {
+            entries[type].push({ path: rel, name: titleFromPath(rel) });
+        }
+    }
+    const pomFiles = allFiles.filter((rel) => rel === "pom.xml" || rel.endsWith("/pom.xml")).sort();
+    const modules = pomFiles.map((rel) => parsePom(repo, rel));
+    const knowledgeFiles = allFiles.filter((rel) => rel.startsWith("knowledge/")).sort();
+    return {
+        schema_version: "1.0",
+        mode,
+        repo,
+        base_commit: currentCommit(repo),
+        worktree_diff_hash: worktreeHash(repo),
+        changed_files: changedFiles(repo),
+        project: {
+            name: path.basename(repo),
+            maven: modules[0] ?? {},
+            modules,
+        },
+        entries,
+        knowledge: {
+            has_manifest: existsSync(path.join(repo, "knowledge/manifest.json")),
+            files: knowledgeFiles,
+            empty_sections: knowledgeFiles
+                .filter((rel) => rel.endsWith("README.md"))
+                .filter((rel) => read(repo, rel).trim().split(/\r?\n/).length <= 3),
+        },
+        candidates: detectCandidates(scopedFiles),
+        sensitive_config_findings: sensitiveFindings(repo, scopedFiles.length ? scopedFiles : allFiles),
+        external_evidence: externalEvidence,
+    };
+}
+function parsePom(repo, rel) {
+    const text = read(repo, rel);
+    const tag = (name) => text.match(new RegExp(`<${name}>\\s*([^<]+?)\\s*</${name}>`))?.[1] ?? "";
+    const modules = [...text.matchAll(/<module>\s*([^<]+?)\s*<\/module>/g)].map((match) => match[1]);
+    return { path: rel, groupId: tag("groupId"), artifactId: tag("artifactId"), version: tag("version"), modules };
+}
+function read(repo, rel) {
+    try {
+        return readFileSync(path.join(repo, rel), "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function entryType(rel) {
+    if (!rel.endsWith(".java"))
+        return "";
+    if (rel.includes("/controller/") || /Controller\.java$/.test(rel))
+        return "controller";
+    if (rel.includes("/service/") || /Service(Impl)?\.java$/.test(rel))
+        return "service";
+    if (rel.includes("/feign/") || /Feign(Service)?(Impl)?\.java$/.test(rel))
+        return "feign";
+    if (rel.includes("/tasks/") || /Task\.java$|Scheduled.*\.java$/.test(rel))
+        return "tasks";
+    if (rel.includes("/mq/") || /Consumer\.java$|Producer\.java$/.test(rel))
+        return "mq";
+    if (rel.includes("/remote/") || /Remote.*\.java$/.test(rel))
+        return "remote";
+    if (rel.includes("/config/") || /Config(uration)?\.java$/.test(rel))
+        return "config";
+    return "";
+}
+function titleFromPath(rel) {
+    return path.basename(rel).replace(/\.(java|xml|ya?ml|properties|md)$/i, "");
+}
+function detectCandidates(files) {
+    const text = files.join("\n").toLowerCase();
+    const has = (items) => items.some((item) => text.includes(item));
+    const domains = [];
+    const workflows = [];
+    const integrations = [];
+    const risks = [];
+    if (has(["goods", "商品"]))
+        domains.push({ target: "knowledge/domains/goods-master.md", reason: "goods domain entry detected" });
+    if (has(["precisionorder", "精准订货"]))
+        domains.push({ target: "knowledge/domains/precision-order.md", reason: "precision order entry detected" });
+    if (has(["hddatasync", "hd", "海鼎"]))
+        workflows.push({ target: "knowledge/workflows/hd-sync.md", reason: "HD sync entry detected" });
+    if (has(["precisionorder", "精准订货"]))
+        workflows.push({ target: "knowledge/workflows/precision-order-flow.md", reason: "precision order workflow detected" });
+    if (has(["mall", "feign", "mq", "remote", "thirdapi"]))
+        integrations.push({ target: "knowledge/integrations/external-systems.md", reason: "external integration entry detected" });
+    if (has(["datafix", "inner", "thirdapi", "password", "secret", "token", "accesskey"]))
+        risks.push({ target: "knowledge/quality/risk-hotspots.md", reason: "risk-sensitive entry detected" });
+    return { domains, workflows, integrations, risks };
+}
+function sensitiveFindings(repo, files) {
+    const findings = [];
+    const configFiles = files.filter((rel) => /(^|\/)application.*\.(ya?ml|properties)$/.test(rel) || rel.includes("/config/"));
+    const rules = [
+        ["builtin.secret.password", /password\s*[:=]\s*\S{3,}/i],
+        ["builtin.secret.token", /token\s*[:=]\s*\S{8,}/i],
+        ["builtin.secret.access-key", /accessKey(Id|Secret)?\s*[:=]\s*\S{8,}/i],
+        ["builtin.secret.generic", /secret\s*[:=]\s*\S{8,}/i],
+    ];
+    for (const rel of configFiles) {
+        const text = read(repo, rel);
+        for (const [ruleId, pattern] of rules) {
+            if (pattern.test(text)) {
+                findings.push({ path: rel, rule_id: ruleId, rule_category: "secret", action: "redact_value" });
+            }
+        }
+    }
+    return findings;
+}
+export function gitChangedFiles(repo) {
+    return runGit(repo, ["diff", "--name-only"]).split(/\r?\n/).filter(Boolean);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export function runGit(repo, args) {
+    try {
+        return execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+export function resolveRepo(input = ".") {
+    if (!existsSync(input)) {
+        throw new Error(`Repository path does not exist: ${input}`);
+    }
+    const root = runGit(input, ["rev-parse", "--show-toplevel"]);
+    if (!root) {
+        throw new Error("project-atlas currently supports Git repositories only.");
+    }
+    return root;
+}
+export function currentCommit(repo) {
+    return runGit(repo, ["rev-parse", "HEAD"]);
+}
+export function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+export function sha256Text(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+export function fileHash(filePath) {
+    if (!existsSync(filePath)) {
+        return "sha256:missing";
+    }
+    return `sha256:${createHash("sha256").update(readFileSync(filePath)).digest("hex")}`;
+}
+export function repoFileHash(repo, rel) {
+    return fileHash(path.join(repo, rel));
+}
+export function writeJson(filePath, value) {
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export function readJson(filePath) {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+}
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+export function writeIfMissing(filePath, content) {
+    if (existsSync(filePath)) {
+        return;
+    }
+    ensureDir(path.dirname(filePath));
+    writeFileSync(filePath, content, "utf8");
+}
+export function walkFiles(repo, dirRel = ".") {
+    const output = [];
+    const root = path.join(repo, dirRel);
+    if (!existsSync(root)) {
+        return output;
+    }
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const rel = dirRel === "." ? entry.name : path.posix.join(toPosix(dirRel), entry.name);
+        if (entry.isDirectory()) {
+            if ([".git", ".project-atlas", ".opencode", ".code-review-graph", "node_modules", "dist", "target"].includes(entry.name)) {
+                continue;
+            }
+            output.push(...walkFiles(repo, rel));
+        }
+        else {
+            output.push(rel);
+        }
+    }
+    return output.sort();
+}
+export function changedFiles(repo) {
+    const values = new Set();
+    for (const args of [
+        ["diff", "--name-only"],
+        ["diff", "--cached", "--name-only"],
+        ["ls-files", "--others", "--exclude-standard"],
+    ]) {
+        for (const line of runGit(repo, args).split(/\r?\n/)) {
+            if (line && !line.startsWith(".project-atlas/")) {
+                values.add(line);
+            }
+        }
+    }
+    return [...values].sort();
+}
+export function worktreeHash(repo) {
+    const parts = [];
+    parts.push(runGit(repo, ["diff", "--binary"]));
+    parts.push(runGit(repo, ["diff", "--cached", "--binary"]));
+    for (const rel of runGit(repo, ["ls-files", "--others", "--exclude-standard"]).split(/\r?\n/).filter(Boolean).sort()) {
+        if (rel.startsWith(".project-atlas/")) {
+            continue;
+        }
+        const abs = path.join(repo, rel);
+        if (!existsSync(abs) || statSync(abs).size > 1024 * 1024) {
+            parts.push(`${rel}\tlarge-or-missing`);
+            continue;
+        }
+        parts.push(`${rel}\t${fileHash(abs)}`);
+    }
+    return sha256Text(parts.join("\n"));
+}
+export function updateGitignore(repo) {
+    const block = [
+        "# >>> project-atlas >>>",
+        ".project-atlas/",
+        "knowledge/**/.kbtmp.*",
+        "knowledge/**/*.kbtmp.*",
+        "# <<< project-atlas <<<",
+        "",
+    ].join("\n");
+    const filePath = path.join(repo, ".gitignore");
+    const current = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+    const start = "# >>> project-atlas >>>";
+    const end = "# <<< project-atlas <<<";
+    if (current.includes(start) && current.includes(end)) {
+        const next = current.replace(new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\n?`, "m"), block);
+        writeFileSync(filePath, next, "utf8");
+        return;
+    }
+    writeFileSync(filePath, `${current}${current && !current.endsWith("\n") ? "\n" : ""}${current ? "\n" : ""}${block}`, "utf8");
+}
+export function ensureEvidenceIgnored(repo) {
+    const ignored = runGit(repo, ["check-ignore", ".project-atlas/proposals/.keep"]);
+    if (!ignored) {
+        throw new Error(".project-atlas/proposals/.keep is not ignored by Git. Run project-atlas init first.");
+    }
+    const tracked = runGit(repo, ["ls-files", ".project-atlas"]);
+    if (tracked) {
+        throw new Error(`.project-atlas is tracked by Git and must be removed from the index first:\n${tracked}`);
+    }
+}
+export function proposalRoot(repo) {
+    return path.join(repo, ".project-atlas", "proposals");
+}
+export function validateKnowledgeTarget(target) {
+    if (/[\r\n\0]/.test(target)) {
+        throw new Error(`Invalid target path: ${target}`);
+    }
+    const normalized = toPosix(path.posix.normalize(target));
+    if (normalized.startsWith("../") || normalized.includes("/../") || path.isAbsolute(normalized)) {
+        throw new Error(`Invalid target path: ${target}`);
+    }
+    if (normalized === "knowledge/manifest.json") {
+        throw new Error("proposal cannot modify knowledge/manifest.json in v1.");
+    }
+    if (normalized.startsWith("knowledge/assets/")) {
+        throw new Error("proposal cannot write knowledge/assets/ in v1.");
+    }
+    if (!normalized.startsWith("knowledge/")) {
+        throw new Error(`proposal target must be under knowledge/**: ${target}`);
+    }
+    return normalized;
+}
+export function replaceFileAtomic(targetPath, content) {
+    ensureDir(path.dirname(targetPath));
+    const tempPath = path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.kbtmp.${process.pid}`);
+    writeFileSync(tempPath, content, "utf8");
+    renameSync(tempPath, targetPath);
+}
+export function removeFileIfExists(filePath) {
+    if (existsSync(filePath)) {
+        unlinkSync(filePath);
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/docs/site/README.md

@@ -0,0 +1,47 @@
+# Project Atlas 文档
+
+这里是 `project-atlas` 的轻量文档入口。文档保持 Markdown 形态，方便直接在 GitHub、编辑器、团队知识库或 agent 上下文里阅读。
+
+English documentation is available at [en/README.md](en/README.md).
+
+如果是 agent 接入，不要从长文档开始。直接读 [Agent Quickstart](agent-quickstart.md)，然后按里面的命令执行。
+
+## 推荐阅读顺序
+
+1. [Agent Quickstart](agent-quickstart.md)
+2. [快速开始](quick-start.md)
+3. [最佳实践](best-practices.md)
+4. [团队落地流程](team-rollout.md)
+5. [安全 FAQ](security-faq.md)
+6. [发布流程](release-process.md)
+7. [现在发布指南](publish-now.md)
+
+## 10 分钟体验路径
+
+```bash
+npm install
+npm run build
+node dist/index.js init --repo /tmp/project-atlas-demo
+node dist/index.js context --repo /tmp/project-atlas-demo --query demo
+node dist/index.js propose --repo /tmp/project-atlas-demo --updates-file updates.json --reason "demo update"
+node dist/index.js review-summary --repo /tmp/project-atlas-demo
+node dist/index.js check --repo /tmp/project-atlas-demo
+```
+
+真实写入仍然要由人回到终端执行：
+
+```bash
+node dist/index.js apply --repo /tmp/project-atlas-demo --proposal-id <id> --confirm
+```
+
+Project Atlas 的核心边界是清楚的。Agent 可以读取上下文和生成 proposal，不能直接 apply。
+
+如果要沉淀项目级记忆，先准备结构化 JSON 候选文件，再生成 proposal：
+
+```bash
+node dist/index.js remember --repo /tmp/project-atlas-demo --candidate-file memory.json --reason "capture project memory"
+```
+
+项目记忆仍然写入 `knowledge/`。它是团队共享知识，不读取个人聊天记录，也不绕过 review。
+
+准备发布 npm 包时，先看 [现在发布指南](publish-now.md)。它给出当前仓库可直接执行的发布前检查、npm 登录、首次发布、打 tag 和推送步骤。