@godcreator/docfirst 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 godcreator02
+
+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

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# god-docsite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 是什么
+
+文档站平台、按功能划分的功能包，以及两个 gwb 工作台插件。任何站点都是「fumadocs 官方 React Router 模板 + 挑选的功能包」：
+平台包 `@godcreator/god-docsite` 带唯一的站点模板与建站器，功能包各自经 fumadocs 与 React Router 原生的扩展点接入站点。
+仓正在重构，设计未定，以代码和 `AGENTS.md` 为准。
+
+| 包（`packages/`） | 做什么 |
+| --- | --- |
+| `@godcreator/god-docsite` | 平台：站点模板与建站器、三种页面来源、布局与侧栏、搜索、llms、推送、术语标注、vite 插件 |
+| `@godcreator/identity`、`@godcreator/comments` | 身份与评论，基础站默认装 |
+| `@godcreator/explainer` | 讲解组件 |
+| `@godcreator/code-pin`、`@godcreator/doc-export`、`@godcreator/trajectory` | 钉码、生成物、轨迹卡与星轨盘 |
+| `@godcreator/docfirst` | 命令行 `docfirst`：核对、确认、生成 |
+| `@godcreator/collab` | 项目协作：任务与模块、日志与日历、通知、合并检查 |
+| `@godcreator/word-report` | 报告：JSON 报告文档、报告列表与报告页、命令行 `report-docx`（检查、导出 Word） |
+
+| 插件（`plugins/`） | 做什么 |
+| --- | --- |
+| `@godcreator/gwb-docsite` | 身份码、建站与加功能、`docfirst.create` 建 docfirst 站、托管站点的开发服务、评论命令，带说明书 `docsite`、`docs-site`、`docs-writing`、`trajectory` |
+| `@godcreator/gwb-collab` | 协作站的项目、提交审核、通知与任务命令 |
+
+## 怎么用
+
+建站与托管在 gwb 工作台里做：`docsite.site.init` 建基础站、`docsite.feature.add` 加功能包、`docsite.site.add` 托管开发服务；
+要钉码与轨迹卡的站用 `docfirst.create {"dir":"<仓>/docs-site"}` 一步建好。
+
+docfirst 站的项目根放一份 `docfirst.config.mjs`（内容根、组件名册、生成物写到哪、轨迹卡目录）。内容根下 `future/` 是未来区，其余目录都是现状区；
+文档里单独写一行不带记录的记号，路径相对项目根：
+
+```mdx
+{/* ref file="src/greet.ts" lines="2-3" */}   行段：这段代码、一条测试、配置里的一个值
+{/* ref file="config.json" */}                整文件：只用在短文件上
+{/* tree dir="src" */}                        目录树；可带 depth="2"、glob="*.test.ts"
+```
+
+然后在站目录里：
+
+```bash
+pnpm doc                                       # 核对（docfirst check）。有红时退出码 1；本仓未提交改动引起的黄也算红
+pnpm doc:confirm                               # 机械写回：给未确认的记号写上记录，挪了位置的写回新行号，重新生成生成物
+pnpm doc:confirm content/docs/a.mdx --accept   # 复核过后，接受点名页里的黄灯；必须点名页
+pnpm doc:render                                # 只重新生成生成物
+```
+
+## 文档在哪
+
+`docs-site/` 是全仓唯一的文档站：总览、fumadocs 原理、写页面、Gitea 与 NAS、维护。轨迹卡在 `docs-site/trajectory/`。
+随插件发布的说明书正本在 `docs-site/content/docs/outputs/skills/`，生成到 `plugins/docsite/skills/` 与 `plugins/collab/skills/`。
+
+**这份 README 与仓根 `CLAUDE.md` 是生成物**（正本在 `docs-site/content/docs/outputs/`），`AGENTS.md` 手写；改 mdx 正本再在 `docs-site/` 里 `pnpm doc:render`。
+
+## 这个仓自己怎么运行
+
+```powershell
+pnpm install
+pnpm build          # 按依赖序构建全部包、两个插件与各站
+pnpm check          # 逐个包跑 check（typecheck、快的一级测试，有 lint 的再 lint），一分钟左右
+pnpm test:slow      # 慢的一级测试（各包的 *.slow.test.ts：真建站、大量调 git 的），只在显式要求时跑，近三分钟
+pnpm test:deps      # 包之间的依赖方向、包内分层、模块之间不许有环（规则在 tests/dependency-rules.cjs，要先 pnpm build）
+pnpm verify         # 最终交付之前（推送、交给人验收、发版前）：build → check → test:slow → test:deps → test:scaffold → test:e2e
+pnpm test:pack      # 发版前再跑：把包打成 tarball 装进测试站的副本，跑同样的端到端检查
+
+cd docs-site
+pnpm doc
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+站点的开发服务都由 gwb-docsite 托管（`docsite.site.add`），不在会话里自己 `pnpm dev`；`pnpm build` 只作提交前的检查。

package/dist/bin.d.mts

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

package/dist/bin.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { n as main } from "./cli-D7N9_iMK.mjs";
+//#region src/bin.ts
+/** docfirst 可执行文件：项目根是当前目录，只转发参数与退出码 */
+process.exit(await main(process.argv.slice(2)));
+//#endregion
+export {};

package/dist/cli-D7N9_iMK.mjs

@@ -0,0 +1,482 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { fumadocsRoster, placementsOf, unknownComponents } from "@godcreator/doc-export";
+import { REASON_TEXT, codeFormat, diffText, parseMdx, targetKey } from "@godcreator/code-pin";
+import { createPinWorkspace, createUncommittedProbe } from "@godcreator/code-pin/node";
+import { assertOutputTurf, renderOutputs, verifyOutputs } from "@godcreator/doc-export/node";
+import { scanCardDir } from "@godcreator/trajectory/node";
+import { buildModel } from "@godcreator/trajectory";
+//#region src/config.ts
+/**
+* 项目根下的 `docfirst.config.mjs`：读进来、按字段表校验、归一成命令行用的形状。
+* 要改的地方一次列全报错；属于站点构建的字段在这里报错，说明它移到了站点配置。
+*/
+const CONFIG_NAME = "docfirst.config.mjs";
+const CONFIG_KEYS = [
+	"content",
+	"components",
+	"fumadocsRoster",
+	"outputs",
+	"trajectory"
+];
+/** 旧配置里属于站点构建的键：命令行不读，遇到就报错并说清它去了哪 */
+const KEYS_MOVED_TO_SITE = { glossary: "术语表的位置与不标注的页由站点声明（站点的 source.ts）" };
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+const isRule = (value) => value === "children" || value === "drop" || typeof value === "function";
+function keyProblems(table) {
+	return Object.keys(table).flatMap((key) => {
+		const movedTo = KEYS_MOVED_TO_SITE[key];
+		if (movedTo !== void 0) return [`${key} 这一项移到站点配置了：${movedTo}，从 ${CONFIG_NAME} 里删掉`];
+		if (!CONFIG_KEYS.includes(key)) return [`不认识的键 ${key}：配置只认 ${CONFIG_KEYS.join(" / ")}`];
+		return [];
+	});
+}
+function componentProblems(components) {
+	if (!isPlainObject(components)) return ["components 要是「组件名 → 规则」的对象"];
+	return Object.entries(components).filter(([, rule]) => !isRule(rule)).map(([name]) => `components.${name} 的规则要是 "children"、"drop" 或函数`);
+}
+/** 配置里要改的地方，一条一句；没有就是空表。只看形状，不读写文件 */
+function configProblems(raw) {
+	if (!isPlainObject(raw)) return [`${CONFIG_NAME} 要 export default 一个对象`];
+	const problems = keyProblems(raw);
+	if (raw.content !== void 0 && !isNonEmptyString(raw.content)) problems.push("content 要是一个非空目录（相对项目根）");
+	if (raw.trajectory !== void 0 && !isNonEmptyString(raw.trajectory)) problems.push("trajectory 要是一个非空目录（相对项目根）");
+	if (raw.fumadocsRoster !== void 0 && typeof raw.fumadocsRoster !== "boolean") problems.push("fumadocsRoster 要是 true 或 false");
+	if (raw.components !== void 0) problems.push(...componentProblems(raw.components));
+	if (raw.outputs !== void 0 && !isPlainObject(raw.outputs)) problems.push("outputs 要是「正本 → 落点数组」的对象");
+	return problems;
+}
+/** 相对项目根的目录：正斜杠、不带尾斜杠 */
+const normalizedDir = (dir) => dir.replace(/\\/g, "/").replace(/\/+$/, "");
+/** 校验过的 default 导出归一成命令行用的形状；落点写法不对由 placementsOf 报错 */
+function normalizedConfig(file) {
+	const contentDir = normalizedDir(file.content ?? "content");
+	return {
+		contentDir,
+		trajectoryDir: file.trajectory === void 0 ? `${contentDir}/trajectory` : normalizedDir(file.trajectory),
+		roster: {
+			...file.fumadocsRoster === true ? fumadocsRoster : {},
+			...file.components
+		},
+		outputs: placementsOf(file.outputs ?? {})
+	};
+}
+/** 校验并归一一份配置；source 是报错里说的配置出处 */
+function parseConfig(raw, source) {
+	const problems = configProblems(raw);
+	if (problems.length > 0) throw new Error(`${source} 有 ${problems.length} 处要改：\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+	return normalizedConfig(raw);
+}
+/** 由 Node 原生加载一个配置模块，交回它的 default 导出 */
+async function importConfigModule(path) {
+	return (await import(pathToFileURL(path).href)).default;
+}
+/** 读项目根下的配置：文件只有 docfirst.config.mjs 这一个名字 */
+async function loadConfig(root) {
+	const path = join(root, CONFIG_NAME);
+	if (!existsSync(path)) throw new Error(`${root} 下没有 ${CONFIG_NAME}——项目根就是放配置的那个目录`);
+	return parseConfig(await importConfigModule(path), path);
+}
+//#endregion
+//#region src/project.ts
+/**
+* 一个项目 = 项目根 + 校验过的配置。装配时定下现状区有哪些文件，备好钉码与生成物两个功能包要的对象。
+*
+* 分区按约定：内容根下 `trajectory/` 与 `future/` 两个名字固定、不进核对；内容根下别的 .mdx 都是现状区，
+* 再加上组件格式认领的代码文件（讲解组件的源码）：现状区里的（页面同名文件夹、组里 `_` 开头的共用文件夹）与站点 `app/components/` 下的。
+*/
+/** 文档身份：相对项目根、正斜杠。绝对路径按项目根算；相对路径原样收，`./` 前缀与反斜杠一并归一 */
+function docIdOf(root, path) {
+	return (isAbsolute(path) ? relative(root, path) : path).split(sep).join("/").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+const NOT_STATUS_AREAS = /* @__PURE__ */ new Set(["trajectory", "future"]);
+const isPage = (name) => name.endsWith(".mdx");
+/** 目录下的全部文件（递归），绝对路径；指向目录的软链接会跟进去 */
+function filesUnderFollowingLinks(dir) {
+	return readdirSync(dir).flatMap((name) => {
+		const path = join(dir, name);
+		return statSync(path).isDirectory() ? filesUnderFollowingLinks(path) : [path];
+	});
+}
+/** 现状区里的全部文件（文档身份）：内容根下除 trajectory/、future/ 之外的 */
+function statusAreaFiles(root, contentAbs) {
+	return readdirSync(contentAbs).flatMap((name) => {
+		const path = join(contentAbs, name);
+		if (statSync(path).isDirectory()) return NOT_STATUS_AREAS.has(name) ? [] : filesUnderFollowingLinks(path).map((file) => docIdOf(root, file));
+		return [docIdOf(root, path)];
+	});
+}
+/** 目录下的全部文件（递归），绝对路径；按目录项自己的类型判断，指向目录的软链接当成文件 */
+function filesUnder(dir) {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name);
+		return entry.isDirectory() ? filesUnder(path) : [path];
+	});
+}
+/** 站点里几组页面共用的组件 */
+const SHARED_COMPONENTS_DIR = "app/components";
+/** 讲解组件以前放的位置：还有文件就报错，不然里面的钉码没人核对 */
+const RETIRED_COMPONENTS_DIR = "src/components";
+function sharedComponentSources(root) {
+	const dir = join(root, SHARED_COMPONENTS_DIR);
+	if (!existsSync(dir)) return [];
+	return filesUnder(dir).map((path) => docIdOf(root, path)).filter(codeFormat.claims);
+}
+function assertNoRetiredComponents(root) {
+	const dir = join(root, RETIRED_COMPONENTS_DIR);
+	if (!existsSync(dir)) return;
+	const files = filesUnder(dir).map((path) => docIdOf(root, path));
+	if (files.length === 0) return;
+	throw new Error(`${RETIRED_COMPONENTS_DIR}/ 下还有文件：${files.join("、")}——讲解组件只给一页用的放进那一页的同名文件夹，几组页面共用的放进 ${SHARED_COMPONENTS_DIR}/，docfirst 只核对这两处的钉码`);
+}
+/** outputs 里的正本得是现状区里的 mdx 页面：写错路径的映射不会被核对，也不会被生成 */
+function assertOutputSourcesAreStatusPages(outputs, docs) {
+	const pages = new Set(docs.filter(isPage));
+	const strays = Object.keys(outputs).filter((doc) => !pages.has(doc));
+	if (strays.length > 0) throw new Error(`outputs 里的正本不是现状区的 mdx 页面：${strays.join("、")}——正本要写相对项目根的路径，放在内容根下（trajectory/、future/ 之外）`);
+}
+function assembleProject(root, config) {
+	const contentAbs = join(root, config.contentDir);
+	if (!existsSync(contentAbs) || !statSync(contentAbs).isDirectory()) throw new Error(`内容根 ${config.contentDir} 不是项目根下的目录——配置的 content 写错了，或者还没建`);
+	assertOutputTurf(root, [config.contentDir], config.outputs);
+	assertNoRetiredComponents(root);
+	const statusFiles = statusAreaFiles(root, contentAbs);
+	const docs = [
+		...statusFiles.filter(isPage),
+		...statusFiles.filter(codeFormat.claims),
+		...sharedComponentSources(root)
+	].sort();
+	assertOutputSourcesAreStatusPages(config.outputs, docs);
+	const pins = createPinWorkspace(root);
+	return {
+		root,
+		config,
+		pins,
+		outputs: {
+			root,
+			outputs: config.outputs,
+			roster: config.roster,
+			pinner: pins.pinner
+		},
+		docs,
+		isOutputSource: (doc) => config.outputs[doc] !== void 0,
+		docIdOf: (path) => docIdOf(root, path),
+		read: (doc) => readFileSync(join(root, doc), "utf8")
+	};
+}
+//#endregion
+//#region src/text.ts
+/**
+* 命令行打印的每一行：状态符号、状态的中文说法、每种结果写成哪一行。只拼字符串，不打印。
+*/
+const MARK = {
+	fresh: "🟢",
+	changed: "🟡",
+	missing: "🔴",
+	unconfirmed: "⚪"
+};
+const LABEL = {
+	fresh: "新鲜",
+	changed: "有变动，等作者复核",
+	missing: "缺失",
+	unconfirmed: "未确认，等作者确认"
+};
+/** 一行说明后面的括号：状态的细分理由（`changed` 就是状态本身，不另说），或目录树的项数 */
+function detailOf(check) {
+	if (check.reason !== void 0 && check.reason !== "changed") return `（${REASON_TEXT[check.reason]}）`;
+	if (check.pin.target.kind !== "tree" || check.current === null) return "";
+	return `（${check.current.length} 项）`;
+}
+/** check 时一处钉的那一行；拦提交的黄单独一种说法，打印成红 */
+function pinCheckLine(doc, check, blocking) {
+	const key = targetKey(check.pin.target);
+	if (blocking) return `🔴 ${doc}  ${key}  有变动，是本仓还没提交的改动引起的${detailOf(check)}——在同一个提交里复核，再 docfirst confirm ${doc} --accept`;
+	return `${MARK[check.status]} ${doc}  ${key}  ${LABEL[check.status]}${detailOf(check)}`;
+}
+/** confirm 时一处钉的那一行；原地没动的绿不打印 */
+function confirmStepLine(doc, { check, action, written, problem }) {
+	const key = targetKey(check.pin.target);
+	switch (action) {
+		case "recorded": return `✅ ${doc}  ${key}  已确认，写上了记录`;
+		case "moved": {
+			const target = written.target;
+			return `✅ ${doc}  ${key}  内容没变、挪到了 ${target.kind === "span" ? `${target.a}-${target.b}` : "新位置"}，已写回新行号`;
+		}
+		case "accepted": return `✅ ${doc}  ${key}  已按今天的内容重新记下`;
+		case "needs-accept": return `🟡 ${doc}  ${key}  ${LABEL.changed}${detailOf(check)}——复核后 docfirst confirm ${doc} --accept`;
+		case "refused": return `🔴 ${doc}  第 ${check.pin.line} 行 ${key}  ${problem ?? `${LABEL.missing}${detailOf(check)}`}，这处没动`;
+		case "unchanged": return null;
+	}
+}
+function unknownComponentLine(doc, name, line) {
+	return `🔴 ${doc}  第 ${line} 行 <${name}>  名册外组件，这篇是生成正本，docfirst.config.mjs 里要给它机读规则`;
+}
+/** 一个落点没生成成功的那一行：源头部缺点名的字段，或源里有渲染不了的东西；again 是改好之后再运行哪条命令 */
+function unwrittenOutputLine(doc, { to, status, missing, reason }, again) {
+	const head = `🔴 ${doc} → ${to}`;
+	if (status === "no-frontmatter") return `${head}  mdx 源的 frontmatter 里没有 ${(missing ?? []).join("、")}——补上再 ${again}`;
+	return `${head}  正本渲染不了：${reason}——改好再 ${again}`;
+}
+/** check 时一个落点的那一行：不新鲜的都红 */
+function outputCheckLine(doc, output) {
+	const head = `${output.fresh ? "🟢" : "🔴"} ${doc} → ${output.to}`;
+	switch (output.status) {
+		case "no-frontmatter":
+		case "unrenderable": return unwrittenOutputLine(doc, output, "render");
+		case "missing": return `${head}  生成物还不存在——运行 render 生成`;
+		case "stale": return `${head}  生成物跟 mdx 源不一致（源改了没重新生成，或有人直接改了生成物）——重新运行 render`;
+		case "fresh": return `${head}  生成物跟 mdx 源一致`;
+	}
+}
+//#endregion
+//#region src/commands/check.ts
+/**
+* check：逐篇核对钉、查生成正本的名册与生成物、校验轨迹卡，先汇总成一份报告再决定怎么输出。
+* 人读模式一处一行，`--json` 打印整份报告；两种模式算的是同一份报告，红的口径对得上。
+*/
+function refReport(check, blocking) {
+	return {
+		target: targetKey(check.pin.target),
+		kind: check.pin.target.kind,
+		status: check.status,
+		line: check.pin.line,
+		lines: check.lines,
+		...check.reason !== void 0 ? { reason: check.reason } : {},
+		...check.diff !== void 0 ? { diff: diffText(check.diff) } : {},
+		...blocking ? { blocking: true } : {}
+	};
+}
+function checkDoc(project, doc, uncommitted) {
+	const text = project.read(doc);
+	const lines = [];
+	const items = [];
+	for (const check of project.pins.pinning.checkDoc(doc, text).checks) {
+		const blocking = check.status === "changed" && uncommitted(doc, check.pin.target);
+		items.push(refReport(check, blocking));
+		lines.push(pinCheckLine(doc, check, blocking));
+	}
+	const isOutputSource = project.isOutputSource(doc);
+	const components = isOutputSource ? unknownComponents(parseMdx(text), project.config.roster) : [];
+	for (const { name, line } of components) lines.push(unknownComponentLine(doc, name, line));
+	const outputs = isOutputSource ? verifyOutputs(project.outputs, [doc]).map(({ doc: _source, ...output }) => output) : [];
+	for (const output of outputs) lines.push(outputCheckLine(doc, output));
+	return {
+		report: {
+			doc,
+			red: items.filter((item) => item.status === "missing" || item.blocking === true).length + components.length + outputs.filter((output) => !output.fresh).length,
+			items,
+			components,
+			outputs
+		},
+		lines
+	};
+}
+/** 轨迹卡校验：卡目录还没建不算红；每条病一条，path 相对项目根 */
+async function checkTrajectory(project) {
+	const dir = join(project.root, project.config.trajectoryDir);
+	const { sick } = await scanCardDir(dir);
+	return sick.flatMap((file) => {
+		const path = relative(project.root, join(dir, file.path)).split(sep).join("/");
+		return file.problems.map((p) => ({
+			path,
+			field: p.field,
+			value: p.value,
+			reason: p.reason
+		}));
+	});
+}
+async function checkCommand(project, json) {
+	const report = {
+		ok: true,
+		red: 0,
+		docs: [],
+		trajectory: []
+	};
+	const uncommitted = createUncommittedProbe(project.root);
+	for (const doc of project.docs) {
+		const { report: entry, lines } = checkDoc(project, doc, uncommitted);
+		report.docs.push(entry);
+		report.red += entry.red;
+		if (!json) for (const line of lines) console.log(line);
+	}
+	report.trajectory = await checkTrajectory(project);
+	report.red += report.trajectory.length;
+	report.ok = report.red === 0;
+	if (json) console.log(JSON.stringify(report));
+	else for (const p of report.trajectory) console.log(`🔴 ${p.path}  ${p.field}：${p.reason}（${p.value}）`);
+	return report.ok ? 0 : 1;
+}
+//#endregion
+//#region src/commands/render.ts
+/**
+* render：生成正本按 outputs 生成到落点，内容变了才写；confirm 最后也走这里重新生成一遍。
+*/
+/** 现状区里的生成正本，按文档身份排序 */
+const outputSourcesOf = (project) => project.docs.filter(project.isOutputSource);
+/** 写一遍全部生成物、逐个落点打印一行，返回没生成成功的落点数；command 是报错里让人改好之后再运行的那条命令 */
+function writeOutputs(project, command) {
+	let red = 0;
+	for (const written of renderOutputs(project.outputs, outputSourcesOf(project))) {
+		const { doc, to, status } = written;
+		if (status === "no-frontmatter" || status === "unrenderable") {
+			console.log(unwrittenOutputLine(doc, written, command));
+			red += 1;
+		} else if (status === "placed") console.log(command === "render" ? `→  ${doc}  摆放到 ${to}` : `→  ${doc}  重新摆放到 ${to}`);
+		else if (command === "render") console.log(`·  ${doc} → ${to}  没变`);
+	}
+	return red;
+}
+function renderCommand(project) {
+	return writeOutputs(project, "render") > 0 ? 1 : 0;
+}
+//#endregion
+//#region src/commands/confirm.ts
+/** 点名的路径换成文档身份；三种路径写法都收，对不上现状区的一并交回，不静默跳过 */
+function pickDocs(project, named) {
+	const alive = new Set(project.docs);
+	const picked = [];
+	const unknown = [];
+	for (const raw of named) {
+		const doc = project.docIdOf(raw);
+		if (alive.has(doc)) picked.push(doc);
+		else unknown.push(raw);
+	}
+	return unknown.length > 0 ? { unknown } : { docs: [...new Set(picked)] };
+}
+/** 一篇的机械写回：逐处打印一行，返回这篇钉不住的处数（红） */
+function confirmDoc(project, doc, accept) {
+	let red = 0;
+	for (const step of project.pins.confirm(doc, { accept }).steps) {
+		const line = confirmStepLine(doc, step);
+		if (line !== null) console.log(line);
+		if (step.action === "refused") red += 1;
+	}
+	return red;
+}
+function confirmCommand(project, named, accept) {
+	if (accept && named.length === 0) {
+		console.error("--accept 要点名页：docfirst confirm <文档路径…> --accept——确认黄灯得说清是哪几页，什么都没动");
+		return 2;
+	}
+	let pages = project.docs;
+	if (named.length > 0) {
+		const picked = pickDocs(project, named);
+		if ("unknown" in picked) {
+			console.error(`不是这个项目里的文档：${picked.unknown.join("、")}——什么都没动`);
+			return 2;
+		}
+		pages = picked.docs;
+		console.log(`·  按页限定：只动 ${pages.join("、")}，别的页不碰`);
+	}
+	let red = 0;
+	for (const doc of pages) red += confirmDoc(project, doc, accept);
+	red += writeOutputs(project, "confirm");
+	return red > 0 ? 1 : 0;
+}
+//#endregion
+//#region src/commands/trajectory.ts
+/**
+* trajectory：读轨迹卡目录、建星轨盘的模型，打印根卡、卡数与每棵树的主干；`--json` 输出盘的输入（盘心、卡、病卡）与树。
+* 只要配置，不装配项目：它不遍历文档。
+*/
+async function trajectoryCommand(root, config, json) {
+	const dir = join(root, config.trajectoryDir);
+	if (!existsSync(dir)) {
+		console.error(`这个项目还没有轨迹卡目录 ${config.trajectoryDir}（相对项目根；位置由配置的 trajectory 定，不写是内容根下的 trajectory/）`);
+		return 2;
+	}
+	const scan = await scanCardDir(dir);
+	const model = buildModel(scan);
+	if (json) {
+		console.log(JSON.stringify({
+			...scan,
+			trees: model.trees
+		}));
+		return 0;
+	}
+	const rootText = model.center ? `${model.center.label}（${model.center.id}）` : "没认出根卡（卡目录里根卡不是恰好一张，见 docfirst check）";
+	console.log(`盘 ${rootText}  ${model.cards.length} 张卡`);
+	for (const tree of model.trees) console.log(`  主干：${tree.spine.join(" → ")}`);
+	const sublineCount = model.trees.reduce((n, t) => n + t.sublines.length, 0);
+	console.log(`  支线 ${sublineCount} 条，孤星 ${model.isolated.length} 张`);
+	return 0;
+}
+//#endregion
+//#region src/cli.ts
+/**
+* 命令行的 main：认命令与开关、读配置、装配项目、交给 commands/ 里的命令，交回退出码。
+* 项目根是传进来的目录（可执行文件传 cwd），那里有 docfirst.config.mjs。main 不调 process.exit，测试与别的程序直接调它。
+*/
+/**
+* 各命令认的开关。不在表里的一律拒绝：confirm 把 `-` 开头的参数从页名里筛掉，开关若被静默忽略，
+* `confirm --dry-run` 就成了不带页名的全部页确认，而且没有任何提示。
+*/
+const FLAGS = {
+	check: ["--json"],
+	confirm: ["--accept"],
+	render: [],
+	trajectory: ["--json"]
+};
+/** 求助的写法：命令位上三种都认，命令后面只认两种开关（`help` 在 confirm 后面可能是页名） */
+const HELP_COMMANDS = /* @__PURE__ */ new Set([
+	"--help",
+	"-h",
+	"help"
+]);
+const HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
+const USAGE = `docfirst——文档钉代码的核对与确认。在有 docfirst.config.mjs 的项目根运行。
+
+  docfirst check [--json]                核对，只读。红退 1；被钉文件在本仓有未提交改动的黄灯也算红，
+                                         在同一个提交里复核并 --accept。--json 出整份机读报告，退出码不变
+  docfirst confirm [文档路径…]            机械写回：未确认的标记写上记录，挪了位置的写回新行号，
+                                         再重新生成挂了 outputs 映射的生成物（内容变了才写）。
+                                         黄灯不动、逐条列出；红的那几处不动、别的照写，有红退 1。
+                                         不带路径 = 全部页；带路径 = 按页限定，只动点名的那几篇
+                                         （例：docfirst confirm content/docs/a.mdx）
+  docfirst confirm <文档路径…> --accept   另外把点名页里的黄灯按今天的内容重新记。复核过才用，必须点名页
+  docfirst render                        把挂了 outputs 映射的生成正本生成到落点（内容变了才写）
+  docfirst trajectory [--json]           列轨迹卡那张盘的树与主干
+  docfirst --help                        打这份用法，什么都不动
+
+不认识的开关一律报错退 2，不会被当作没写。`;
+function parseArgs(argv) {
+	const [command = "check", ...rest] = argv;
+	if (HELP_COMMANDS.has(command) || rest.some((arg) => HELP_FLAGS.has(arg))) return { help: true };
+	const allowed = FLAGS[command];
+	if (allowed === void 0) return { error: `不认识的命令：${command}——有 ${Object.keys(FLAGS).join(" / ")}，用法看 docfirst --help` };
+	const flags = rest.filter((arg) => arg.startsWith("-"));
+	const unknown = flags.filter((flag) => !allowed.includes(flag));
+	if (unknown.length > 0) {
+		const said = allowed.length === 0 ? "不收任何开关" : `只认 ${allowed.join(" / ")}`;
+		return { error: `${command} 不认识开关 ${unknown.join(" ")}（${command} ${said}），什么都没动。用法看 docfirst --help` };
+	}
+	const paths = rest.filter((arg) => !arg.startsWith("-"));
+	if (command !== "confirm" && paths.length > 0) return { error: `${command} 不收文档路径（${paths.join(" ")}）——只有 confirm 能点名页，什么都没动。用法看 docfirst --help` };
+	return {
+		command,
+		flags,
+		paths
+	};
+}
+async function main(argv, root = process.cwd()) {
+	const parsed = parseArgs(argv);
+	if ("help" in parsed) {
+		console.log(USAGE);
+		return 0;
+	}
+	if ("error" in parsed) {
+		console.error(parsed.error);
+		return 2;
+	}
+	const { command, flags, paths } = parsed;
+	const config = await loadConfig(root);
+	if (command === "trajectory") return trajectoryCommand(root, config, flags.includes("--json"));
+	const project = assembleProject(root, config);
+	if (command === "check") return checkCommand(project, flags.includes("--json"));
+	if (command === "confirm") return confirmCommand(project, paths, flags.includes("--accept"));
+	return renderCommand(project);
+}
+//#endregion
+export { loadConfig as a, configProblems as i, main as n, parseConfig as o, assembleProject as r, USAGE as t };

package/dist/index.d.mts

@@ -0,0 +1,94 @@
+import { OutputPlacement, OutputsConfig, Roster } from "@godcreator/doc-export";
+import { Reason, Status, Target } from "@godcreator/code-pin";
+import { PinWorkspace } from "@godcreator/code-pin/node";
+import { OutputCheck, OutputProject } from "@godcreator/doc-export/node";
+//#region src/cli.d.ts
+declare const USAGE = "docfirst——文档钉代码的核对与确认。在有 docfirst.config.mjs 的项目根运行。\n\n  docfirst check [--json]                核对，只读。红退 1；被钉文件在本仓有未提交改动的黄灯也算红，\n                                         在同一个提交里复核并 --accept。--json 出整份机读报告，退出码不变\n  docfirst confirm [文档路径…]            机械写回：未确认的标记写上记录，挪了位置的写回新行号，\n                                         再重新生成挂了 outputs 映射的生成物（内容变了才写）。\n                                         黄灯不动、逐条列出；红的那几处不动、别的照写，有红退 1。\n                                         不带路径 = 全部页；带路径 = 按页限定，只动点名的那几篇\n                                         （例：docfirst confirm content/docs/a.mdx）\n  docfirst confirm <文档路径…> --accept   另外把点名页里的黄灯按今天的内容重新记。复核过才用，必须点名页\n  docfirst render                        把挂了 outputs 映射的生成正本生成到落点（内容变了才写）\n  docfirst trajectory [--json]           列轨迹卡那张盘的树与主干\n  docfirst --help                        打这份用法，什么都不动\n\n不认识的开关一律报错退 2，不会被当作没写。";
+declare function main(argv: readonly string[], root?: string): Promise<number>;
+//#endregion
+//#region src/config.d.ts
+/** `docfirst.config.mjs` 的 default 导出，字段表的正本 */
+interface DocfirstConfigFile {
+  /** 内容根，相对项目根；不写是 content */
+  content?: string;
+  /** 组件名册：组件名 → 机读规则（"children" / "drop" / 函数）；生成正本里用到的组件都得在名册里 */
+  components?: Roster;
+  /** true：先用 doc-export 现成的 fumadocs 名册（Note、Files、Folder、File），components 里同名的规则盖过它 */
+  fumadocsRoster?: boolean;
+  /** 生成物：正本（相对项目根）→ 落点数组；落点写相对项目根的路径，或 { to, frontmatter } */
+  outputs?: OutputsConfig;
+  /** 轨迹卡目录，相对项目根；不写是内容根下的 trajectory/ */
+  trajectory?: string;
+}
+/** 校验并归一之后的配置：目录都相对项目根、正斜杠、不带尾斜杠 */
+interface DocfirstConfig {
+  contentDir: string;
+  trajectoryDir: string;
+  /** 用来查名册与生成生成物的那张表：fumadocs 名册（选了才有）加上 components */
+  roster: Roster;
+  outputs: Record<string, OutputPlacement[]>;
+}
+/** 配置里要改的地方，一条一句；没有就是空表。只看形状，不读写文件 */
+declare function configProblems(raw: unknown): string[];
+/** 校验并归一一份配置；source 是报错里说的配置出处 */
+declare function parseConfig(raw: unknown, source: string): DocfirstConfig;
+/** 读项目根下的配置：文件只有 docfirst.config.mjs 这一个名字 */
+declare function loadConfig(root: string): Promise<DocfirstConfig>;
+//#endregion
+//#region src/project.d.ts
+interface Project {
+  root: string;
+  config: DocfirstConfig;
+  /** 钉码：读工作区、旧内容从 git 取 */
+  pins: PinWorkspace;
+  /** 生成物：落点、名册、和 pins 同一个钉码核心 */
+  outputs: OutputProject;
+  /** 现状区里的文件：相对项目根、正斜杠、排过序 */
+  docs: string[];
+  /** 这篇是不是生成正本（outputs 里有它） */
+  isOutputSource(doc: string): boolean;
+  docIdOf(path: string): string;
+  read(doc: string): string;
+}
+declare function assembleProject(root: string, config: DocfirstConfig): Project;
+//#endregion
+//#region src/report.d.ts
+/** 一个生成物落点的状态：doc-export 的核对结果，去掉报告里已经由外层给出的正本身份 */
+type OutputReport = Omit<OutputCheck, "doc">;
+interface RefReport {
+  /** 目标的文本形态，同人读报告里的那一截（`file:a-b`、`tree dir depth=1`……） */
+  target: string;
+  kind: Target["kind"];
+  status: Status;
+  /** 标记在文件里的第几行，1 起 */
+  line: number;
+  lines: [number, number];
+  reason?: Reason;
+  diff?: string;
+  blocking?: true;
+}
+interface ComponentReport {
+  name: string;
+  line: number;
+}
+interface DocReport {
+  doc: string;
+  red: number;
+  items: RefReport[];
+  components: ComponentReport[];
+  outputs: OutputReport[];
+}
+interface CardProblemReport {
+  path: string;
+  field: string;
+  value: string;
+  reason: string;
+}
+interface CheckReport {
+  ok: boolean;
+  red: number;
+  docs: DocReport[];
+  trajectory: CardProblemReport[];
+}
+//#endregion
+export { type CardProblemReport, type CheckReport, type ComponentReport, type DocReport, type DocfirstConfig, type DocfirstConfigFile, type OutputReport, type Project, type RefReport, USAGE, assembleProject, configProblems, loadConfig, main, parseConfig };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { t as USAGE, r as assembleProject, i as configProblems, a as loadConfig, n as main, o as parseConfig } from "./cli-D7N9_iMK.mjs";

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@godcreator/docfirst",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "author": {
+    "name": "godcreator"
+  },
+  "type": "module",
+  "description": "docfirst 命令行：读项目根的 docfirst.config.mjs，把 check / confirm / render / trajectory 分派给钉码（code-pin）、生成物（doc-export）、轨迹卡（trajectory）三个功能包，汇总结果、给出退出码。template/ 是文档维护的起始物（配置、生成物正本、起始页、第一张轨迹卡），建站后叠在站点根上。",
+  "license": "MIT",
+  "bin": {
+    "docfirst": "./dist/bin.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "template",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@godcreator/code-pin": "^0.2.0",
+    "@godcreator/doc-export": "^0.1.0",
+    "@godcreator/trajectory": "^0.1.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/godcreator02/god-docsite.git",
+    "directory": "packages/docfirst"
+  },
+  "keywords": [
+    "gwb"
+  ]
 }

package/template/content/docs/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "现状",
+  "pages": ["outputs"]
+}

package/template/content/docs/outputs/agents.mdx

@@ -0,0 +1,14 @@
+---
+title: AGENTS
+---
+
+# 仓的规矩
+
+这一页是仓根 AGENTS.md 的正本：`pnpm doc:render` 把它生成过去，改这里、不改那边，两份放进同一个提交。
+写给在这个仓干活的 agent 看，至少写清：
+
+- 用什么语言回复、注释与提交信息用什么语言
+- 怎么装依赖、构建、跑测试，提交前哪些检查要绿
+- 这个仓里有哪些接缝与边界不许跨
+
+各客户端都该遵守的规矩写在这里；只给某一个客户端的指令写进 claude.mdx 那份正本。

package/template/content/docs/outputs/claude.mdx

@@ -0,0 +1,7 @@
+---
+title: CLAUDE
+---
+
+@AGENTS.md
+
+只给 Claude 的指令写在上面那一行的后面；各客户端都该遵守的规矩写进 agents.mdx 那份正本。

package/template/content/docs/outputs/readme.mdx

@@ -0,0 +1,10 @@
+---
+title: README
+---
+
+# 这个项目的名字
+
+这一页是仓根 README.md 的正本：`pnpm doc:render` 把它生成过去，改这里、不改那边，
+两份放进同一个提交，`pnpm doc` 会检查它们一致。删掉这页前先把 docfirst.config.mjs 里对应的 outputs 映射去掉。
+
+往下写：这个仓是什么、怎么跑起来（装依赖、构建、测试各一条命令）、从哪开始读。

package/template/content/future/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "未来",
+  "pages": ["overview"]
+}

package/template/content/future/overview.mdx

@@ -0,0 +1,8 @@
+---
+title: 未来区
+---
+
+未来区记还没做的事：打算怎么做、做到哪一步了。每件事一页，写进 `content/future/` 下。
+
+与现状区的差别：现状区（`content/` 下其余的页面）钉的是代码今天的样子，`pnpm doc` 核对它们与代码一致；
+未来区不钉码、不进核对，写的是计划与进度。这一页是起始页，改掉它或删掉它都行。

package/template/docfirst.config.mjs

@@ -0,0 +1,26 @@
+/**
+ * 这个项目的 docfirst 配置：命令行 docfirst（check / confirm / render / trajectory）读它，项目根是站点目录。
+ *
+ * content：内容根。下面的 future/ 是未来区、不进核对，其余目录都是现状区、都进 check。
+ * outputs：仓根（站点目录的上一级）的 README.md / AGENTS.md / CLAUDE.md 是生成物，正本是映射左边的 mdx——
+ * 改了正本运行 `pnpm doc:render`，两份放进同一个提交，`pnpm doc` 检查生成物跟正本是否一致。
+ * CLAUDE.md 第一行固定是 `@AGENTS.md`，只给 Claude 的指令写在它后面。
+ * fumadocsRoster 与 components：组件名册。fumadocsRoster 放进 fumadocs 自带的 Note、Files、Folder、File 的机读规则，
+ * components 再加站里的组件；站里自己加组件，就在 components 里给它加一条机读规则（怎么写见 skill「docs-writing」）。
+ * trajectory：轨迹卡放在站点根下的 trajectory/，站点的卡集合（app/features/trajectory/mdx.ts）读同一个目录。
+ * 术语表不在这里：它是站点根的 glossary.json，由站点的 source.config.ts 交给术语标注插件。
+ */
+export default {
+  content: "content",
+  outputs: {
+    "content/docs/outputs/readme.mdx": ["../README.md"],
+    "content/docs/outputs/agents.mdx": ["../AGENTS.md"],
+    "content/docs/outputs/claude.mdx": ["../CLAUDE.md"],
+  },
+  fumadocsRoster: true,
+  components: {
+    // 手写的术语标注：机读版里只留术语原词
+    Term: "children",
+  },
+  trajectory: "trajectory",
+};

package/template/trajectory/2026-01-01-site-born.md

@@ -0,0 +1,12 @@
+---
+born-at: 2026-01-01T00:00
+type: root
+label: 起始
+---
+
+## 背景
+
+这一张是建站时放的起始卡：星轨盘要有一张根卡当盘心，卡目录里没有根卡就画不出盘。
+
+把它改成这个站的第一张真卡（label、born-at 都换成真的），或者删掉它、写自己的根卡。
+卡怎么写看随工作台插件发的 skill「trajectory」。