@biaoo/tiangong-wiki 0.2.0 → 0.2.2

package/assets/templates/method.md

@@ -14,18 +14,26 @@ effectiveness:
 applicableTo: []
 ---
 
-## 方法描述
+## Purpose & Mechanism
 
-先用一段完整的话解释这套方法的目标、输入、输出和基本流程。
+State what problem this method solves and why it works. Do not restate the title — explain the underlying mechanism or principle that makes this method effective.
 
-## 适用场景
+## Steps / Procedure
 
-说明这套方法在什么问题、约束和前置条件下最值得使用。
+List the concrete steps to execute this method. Each step should be actionable and verifiable. If the method has variants, describe the core sequence first, then note variations.
 
-## 不适用场景
+## Applicable Scenarios
 
-写出哪些边界条件会让这套方法失效，避免未来被误用。
+Specify the preconditions, input types, and constraints under which this method is the right choice. Be concrete — name the kind of problem, data, or situation, not just "when appropriate."
 
-## 使用记录
+## Inapplicable Scenarios
 
-记录真实使用过它的场景、结果、指标或反馈，支撑 effectiveness 的判断。
+State when this method should NOT be used. Name the boundary conditions, failure triggers, or assumptions that must hold. If these break, what goes wrong?
+
+## Failure Modes
+
+Describe how this method fails when misapplied. What does a bad outcome look like? What early signals indicate the method is not working? This section prevents blind reuse.
+
+## Evidence
+
+Record real uses of this method with measurable outcomes. Include context, results, and comparison baselines where available. Do not write "it worked well" without specifics — state what was measured and what changed.

package/assets/templates/misconception.md

@@ -14,22 +14,22 @@ resolvedAt:
 correctedConcepts: []
 ---
 
-## 原来的理解（错误）
+## False Belief
 
-准确写下当时错误的理解，不要提前替它辩护或修正。
+State the incorrect understanding exactly as it was held — without softening, defending, or pre-correcting it. A reader should be able to recognize this belief if they currently hold it.
 
-## 为什么错了
+## Why It Is Wrong
 
-说明哪条证据、哪个反例或哪个推理步骤暴露了原理解的问题。
+Identify the specific evidence, counterexample, or reasoning flaw that disproves the false belief. Do not just assert it is wrong — show the proof.
 
-## 正确理解
+## Correct Understanding
 
-用清晰的语言写出现在确认正确的理解，并指出关键差异。
+State the corrected understanding clearly and precisely. Highlight the key difference from the false belief — what specifically changes?
 
-## 转折点
+## Turning Point
 
-记录让你真正完成认知切换的瞬间、材料或实验结果。
+Record the moment, material, experiment, or conversation that caused the actual cognitive shift. If no single turning point exists, this section may be omitted.
 
-## 防止复发
+## Recurrence Prevention
 
-写下未来再次遇到相似问题时，应该用什么检查点防止重复犯错。
+Write the checks, questions, or heuristics to apply in the future to avoid falling back into this misconception. Each item should be a concrete test, not a vague reminder.

package/assets/templates/person.md

@@ -14,18 +14,18 @@ context:
 contact:
 ---
 
-## 基本信息
+## Identity & Role
 
-写清楚这个人的身份、角色、与你的关系以及为什么值得长期记录。
+State this person's name, professional role, organization, and domain expertise. Focus on facts that make this person a reusable knowledge node — not personal relationship notes.
 
-## 共事内容
+## Context & Collaboration
 
-说明你们在哪些项目、主题或情境中有过协作、交流或影响。
+Describe the projects, domains, or initiatives where this person is relevant. Link to existing wiki pages for shared projects or topics. This section should help graph traversal — a reader should understand why this person node connects to other knowledge.
 
-## 从他/她那学到的
+## Key Contributions
 
-记录这个人带来的关键认知、做事方式、提醒或可复用的经验。
+Record this person's notable contributions, decisions, or expertise that are valuable beyond a single interaction. Write facts and outcomes, not impressions. If contributions are significant enough, they should be separate achievement pages linked via relatedPages.
 
-## 备忘
+## Notes
 
-写下未来互动时需要记住的事项，例如偏好、待跟进事项或联系线索。
+Brief factual notes for future reference: contact preferences, scheduling constraints, areas of ongoing work. Keep this minimal — this is not a personal diary entry.

package/assets/templates/research-note.md

@@ -13,22 +13,22 @@ researchTopic:
 stage:
 ---
 
-## 研究问题
+## Research Question
 
-明确写下当前真正要回答的问题，以及为什么这个问题值得继续研究。
+State the specific question being investigated and why it matters. A well-scoped question should be falsifiable or at least answerable with evidence.
 
-## 已读文献
+## Literature & Sources
 
-汇总已经读过的来源、它们分别提供了什么线索，以及哪些结论彼此冲突。
+List sources consulted so far. For each, note: what it contributes (supports / contradicts / is tangential) and what key claim or data it provides. Link to source-summary pages where they exist.
 
-## 当前理解
+## Working Hypothesis
 
-用你自己的话总结目前的工作假设、解释框架或初步结论。
+State your current best explanation or framework. Label it explicitly as a hypothesis — this is not a conclusion. Include the assumptions it rests on.
 
-## 开放问题
+## Open Questions
 
-列出尚未解决的疑点、反例、数据缺口或需要验证的推断。
+List unresolved issues: contradictory evidence, data gaps, untested assumptions, or alternative explanations you have not yet ruled out.
 
-## 下一步
+## Next Actions
 
-说明下一轮最值得做的阅读、实验、访谈或验证动作。
+Describe the specific next steps: what to read, test, build, or ask. Each action should be concrete enough to execute immediately — "research more" is not an action.

package/assets/templates/resume.md

@@ -11,24 +11,25 @@ createdAt: 2026-04-06
 updatedAt: 2026-04-06
 targetAudience:
 lastReviewedAt:
+vaultPath:
 ---
 
-## 基本信息
+## Positioning
 
-先写出这份 resume 面向谁、主打什么定位，以及希望读者一眼记住什么。
+State the target audience for this resume and the core professional identity in one sentence. What should the reader remember after 10 seconds?
 
-## 教育/工作背景
+## Education & Work Background
 
-按与你的目标最相关的顺序整理教育、工作或长期项目背景，而不是机械罗列。
+List education and work history in order of relevance to the target audience, not chronological order. Keep entries factual — institution, role, duration, key focus. Do not expand into narratives here.
 
-## 核心技能
+## Core Skills
 
-写出最能支撑当前目标 audience 的技能、能力证据和熟练程度。
+List skills with evidence of proficiency. For each skill, either link to a wiki page that demonstrates it or note the context where it was applied. Do not list skills without supporting evidence.
 
-## 项目经历
+## Selected Projects
 
-挑选最有代表性的项目，说明问题、动作、结果以及你的具体贡献。
+Choose the most representative projects. For each: state the problem, your specific role, the action taken, and the measurable outcome. If a project has its own wiki page, link to it rather than repeating the description here.
 
-## 荣誉与成就
+## Honors & Achievements
 
-汇总最能增强可信度的 achievement、奖项、认证或公开证明材料。
+Reference existing achievement pages via relatedPages where possible. For items not yet captured as achievement pages, provide a one-line summary with verifiable evidence (certificate, publication, link).

package/assets/templates/source-summary.md

@@ -14,22 +14,18 @@ vaultPath:
 keyFindings: []
 ---
 
-## 来源信息
+## Source Identity
 
-交代这份来源是什么、来自哪里、为什么值得被单独消化成 wiki 页面。
+State what this source is (document type, author, date, context) and why it was preserved as a source-summary rather than extracted into a more specific knowledge type. If the source contains extractable concepts, methods, or lessons, those should be separate pages — not folded into this summary.
 
-## 核心内容
+## Key Claims
 
-用结构化段落总结这份来源的主题、结构和主要论点，而不是只写一句话。
+List the independently quotable factual claims, data points, or conclusions from this source. Each item should be a self-contained assertion, not a topic heading. Do not paraphrase broadly — capture what the source actually states.
 
-## 关键结论
+## Knowledge Connections
 
-列出对后续决策、学习或项目推进最重要的结论与发现。
+Identify which existing wiki pages this source supports, extends, challenges, or contradicts. Name specific pages and describe the relationship. Keep `sourceRefs` and `relatedPages` aligned with the key connections, but do not repeat them mechanically in prose. Use the body only to explain the relationship.
 
-## 与已有知识的关系
+## Evidence Pointers
 
-说明这份来源会补强、修正或挑战哪些现有 concept、method 或 lesson 页面。
-
-## 重要引用
-
-摘录最值得回看的句子、数据点、章节或页码线索，帮助以后快速回源。
+Optionally capture only the evidence needed for fast source recovery: short excerpts, exact data points, and precise locators such as page numbers, section headings, figure labels, or timestamps. Do not restate `sourceRefs`, and do not turn this section into a quote dump. Use it only when exact evidence localization would save future rereading.

package/assets/wiki.config.default.json

@@ -91,7 +91,8 @@
       "file": "templates/source-summary.md",
       "columns": {
         "sourceType": "text",
-        "vaultPath": "text"
+        "vaultPath": "text",
+        "keyFindings": "text"
       },
       "edges": {},
       "summaryFields": [
@@ -116,7 +117,8 @@
       "file": "templates/method.md",
       "columns": {
         "domain": "text",
-        "effectiveness": "text"
+        "effectiveness": "text",
+        "applicableTo": "text"
       },
       "edges": {},
       "summaryFields": [
@@ -159,7 +161,8 @@
       "file": "templates/resume.md",
       "columns": {
         "targetAudience": "text",
-        "lastReviewedAt": "text"
+        "lastReviewedAt": "text",
+        "vaultPath": "text"
       },
       "edges": {},
       "summaryFields": [

package/dist/commands/asset.js

@@ -0,0 +1,21 @@
+import { refAsset, saveAsset } from "../operations/asset.js";
+import { writeJson } from "../utils/output.js";
+export function registerAssetCommand(program) {
+    const asset = program.command("asset").description("Manage wiki assets (images, files)");
+    asset
+        .command("save <source-file>")
+        .description("Save a file to wiki assets directory")
+        .option("--name <slug>", "Target filename in kebab-case, without extension")
+        .option("--type <asset-type>", "Asset type (determines subdirectory)", "image")
+        .action(async (sourceFile, options) => {
+        writeJson(saveAsset(process.env, sourceFile, options));
+    });
+    asset
+        .command("ref <asset-path-or-name>")
+        .description("Compute relative path from a page to an asset")
+        .requiredOption("--page <page-id>", "Page ID that will reference this asset")
+        .option("--type <asset-type>", "Asset type (determines lookup directory)", "image")
+        .action(async (assetPathOrName, options) => {
+        writeJson(refAsset(process.env, assetPathOrName, options));
+    });
+}

package/dist/commands/skill.js

@@ -0,0 +1,78 @@
+import { addManagedSkill, getManagedSkillStatus, updateManagedSkills } from "../core/workspace-skills.js";
+import { AppError } from "../utils/errors.js";
+import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
+function renderSkillStatus(payload) {
+    return payload.skills.map((item) => `${item.name}: ${item.state}\n  ${item.message}`).join("\n");
+}
+function resolveTargetNames(name, all, options = {}) {
+    if (name && all) {
+        throw new AppError("Pass either a skill name or --all, not both.", "config");
+    }
+    if (!name && !all && options.requireSelection) {
+        throw new AppError("Pass a skill name or --all.", "config");
+    }
+    if (!name && !all) {
+        return undefined;
+    }
+    return name ? [name] : undefined;
+}
+export function registerSkillCommand(program) {
+    const skill = program.command("skill").description("Inspect, install, and update workspace-local managed skills");
+    skill
+        .command("add")
+        .argument("<source>", "Skill source repo URL or local path")
+        .requiredOption("--skill <name>", "Skill name")
+        .option("--force", "Replace local conflicting changes with the latest managed snapshot")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (source, options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = {
+            results: [
+                addManagedSkill(process.env, source, options.skill ?? "", {
+                    force: Boolean(options.force),
+                }),
+            ],
+        };
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(payload.results
+            .map((item) => `${item.name}: ${item.action} (${item.state})\n  ${item.message}`)
+            .join("\n"));
+    });
+    skill
+        .command("status")
+        .argument("[name]", "Optional skill name")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (name, options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = { skills: getManagedSkillStatus(process.env, name ? [name] : undefined) };
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(renderSkillStatus(payload));
+    });
+    skill
+        .command("update")
+        .argument("[name]", "Optional skill name")
+        .option("--all", "Update all managed skills")
+        .option("--force", "Replace local conflicting changes with the latest managed snapshot")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (name, options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = {
+            results: updateManagedSkills(process.env, resolveTargetNames(name, Boolean(options.all), { requireSelection: true }), {
+                force: Boolean(options.force),
+            }),
+        };
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(payload.results
+            .map((item) => `${item.name}: ${item.action} (${item.state})\n  ${item.message}`)
+            .join("\n"));
+    });
+}

package/dist/commands/template.js

@@ -1,4 +1,5 @@
 import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { renderTemplateLintResult, runTemplateLint } from "../operations/template-lint.js";
 import { createTemplate, listTemplates, showTemplate } from "../operations/type-template.js";
 import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
 export function registerTemplateCommand(program) {
@@ -45,6 +46,35 @@ export function registerTemplateCommand(program) {
         }
         writeText(String(payload.content ?? ""));
     });
+    template
+        .command("lint")
+        .argument("[pageType]", "Optional pageType to lint")
+        .option("--level <level>", "error, warning, or info", "info")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (pageType, options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => runTemplateLint(process.env, {
+                pageType: typeof pageType === "string" ? pageType : undefined,
+                level: options.level ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/template/lint",
+                query: {
+                    pageType: typeof pageType === "string" ? pageType : undefined,
+                    level: options.level ?? undefined,
+                },
+            }),
+        });
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(renderTemplateLintResult(payload));
+    });
     template
         .command("create")
         .requiredOption("--type <pageType>", "New pageType")

package/dist/core/cli-env.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { readGlobalConfig } from "./global-config.js";
 import { pathExistsSync, readTextFileSync } from "../utils/fs.js";
 export const DEFAULT_WIKI_ENV_FILE = ".wiki.env";
 const EMPTY_INFO = {
@@ -6,6 +7,10 @@ const EMPTY_INFO = {
     loadedPath: null,
     autoDiscovered: false,
     missingRequestedPath: false,
+    missingDefaultPath: false,
+    source: "none",
+    globalConfigPath: null,
+    defaultPath: null,
     loadedKeys: [],
 };
 let lastCliEnvInfo = EMPTY_INFO;
@@ -86,20 +91,40 @@ export function applyCliEnvironment(targetEnv = process.env, cwd = process.cwd()
     const requestedEnvFile = targetEnv.WIKI_ENV_FILE?.trim();
     const requestedPath = requestedEnvFile ? path.resolve(cwd, requestedEnvFile) : null;
     if (!requestedPath && hasExplicitCoreRuntimeEnv(targetEnv)) {
-        lastCliEnvInfo = { ...EMPTY_INFO };
+        lastCliEnvInfo = { ...EMPTY_INFO, source: "process-env" };
         return lastCliEnvInfo;
     }
-    const candidatePath = requestedPath ?? findNearestEnvFile(cwd);
+    const nearestPath = requestedPath ? null : findNearestEnvFile(cwd);
+    const globalConfig = requestedPath || nearestPath ? null : readGlobalConfig(targetEnv);
+    const defaultPath = globalConfig ? path.resolve(globalConfig.defaultEnvFile) : null;
+    const candidatePath = requestedPath ?? nearestPath ?? defaultPath;
+    const source = requestedPath
+        ? "explicit-env-file"
+        : nearestPath
+            ? "nearest-env-file"
+            : defaultPath
+                ? "global-default-env-file"
+                : "none";
     if (!candidatePath) {
-        lastCliEnvInfo = { ...EMPTY_INFO, requestedPath };
+        lastCliEnvInfo = {
+            ...EMPTY_INFO,
+            requestedPath,
+            source,
+            globalConfigPath: globalConfig?.configPath ?? null,
+            defaultPath,
+        };
         return lastCliEnvInfo;
     }
     if (!pathExistsSync(candidatePath)) {
         lastCliEnvInfo = {
             requestedPath: candidatePath,
             loadedPath: null,
-            autoDiscovered: false,
+            autoDiscovered: source === "nearest-env-file",
             missingRequestedPath: requestedPath !== null,
+            missingDefaultPath: requestedPath === null && source === "global-default-env-file",
+            source,
+            globalConfigPath: globalConfig?.configPath ?? null,
+            defaultPath,
             loadedKeys: [],
         };
         return lastCliEnvInfo;
@@ -118,8 +143,12 @@ export function applyCliEnvironment(targetEnv = process.env, cwd = process.cwd()
     lastCliEnvInfo = {
         requestedPath,
         loadedPath: candidatePath,
-        autoDiscovered: requestedPath === null,
+        autoDiscovered: source === "nearest-env-file",
         missingRequestedPath: false,
+        missingDefaultPath: false,
+        source,
+        globalConfigPath: globalConfig?.configPath ?? null,
+        defaultPath,
         loadedKeys,
     };
     return lastCliEnvInfo;

package/dist/core/global-config.js

@@ -0,0 +1,61 @@
+import os from "node:os";
+import path from "node:path";
+import { AppError } from "../utils/errors.js";
+import { ensureDirSync, pathExistsSync, readTextFileSync, writeTextFileSync } from "../utils/fs.js";
+export const GLOBAL_CONFIG_DIRNAME = "tiangong-wiki";
+export const GLOBAL_CONFIG_FILENAME = "config.json";
+function resolveConfigBaseDir(env = process.env) {
+    const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
+    if (xdgConfigHome) {
+        return path.resolve(xdgConfigHome);
+    }
+    const homeDir = env.HOME?.trim() || os.homedir();
+    return path.join(homeDir, ".config");
+}
+export function resolveGlobalConfigPath(env = process.env) {
+    return path.join(resolveConfigBaseDir(env), GLOBAL_CONFIG_DIRNAME, GLOBAL_CONFIG_FILENAME);
+}
+export function readGlobalConfig(env = process.env) {
+    const configPath = resolveGlobalConfigPath(env);
+    if (!pathExistsSync(configPath)) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readTextFileSync(configPath));
+    }
+    catch (error) {
+        throw new AppError(`Failed to parse global CLI config JSON: ${configPath}`, "config", {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AppError(`Global CLI config must be an object: ${configPath}`, "config");
+    }
+    const schemaVersion = parsed.schemaVersion;
+    if (!Number.isInteger(schemaVersion) || Number(schemaVersion) < 1) {
+        throw new AppError(`Global CLI config schemaVersion must be a positive integer: ${configPath}`, "config");
+    }
+    const defaultEnvFile = parsed.defaultEnvFile;
+    if (typeof defaultEnvFile !== "string" || defaultEnvFile.trim().length === 0) {
+        throw new AppError(`Global CLI config defaultEnvFile must be a non-empty string: ${configPath}`, "config");
+    }
+    return {
+        configPath,
+        defaultEnvFile: path.resolve(defaultEnvFile),
+    };
+}
+export function writeGlobalConfig(defaultEnvFile, env = process.env) {
+    const configPath = resolveGlobalConfigPath(env);
+    const normalizedEnvFile = path.resolve(defaultEnvFile);
+    const payload = {
+        schemaVersion: 1,
+        defaultEnvFile: normalizedEnvFile,
+    };
+    ensureDirSync(path.dirname(configPath));
+    writeTextFileSync(configPath, `${JSON.stringify(payload, null, 2)}\n`);
+    return {
+        configPath,
+        defaultEnvFile: normalizedEnvFile,
+    };
+}