@dokebi/cli 0.2.4 → 0.4.0

package/dist/plugin-lifecycle.js

@@ -11,6 +11,8 @@ import { packageFile, workspaceRootOf } from './workspace.js';
 const HINT = /^[^\p{Cc}]{1,200}$/u;
 const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
 const KEY = /^[A-Za-z0-9_-]{1,64}$/;
+/** An environment variable name a plan may ask a generated secret for. */
+export const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 export function optionsOf(options, id) {
     const value = Object.hasOwn(options, id) ? options[id] : undefined;
     return value === undefined || value === null ? {} : object(value, 'plugin options');
@@ -39,6 +41,19 @@ export function optionPath(value) {
     }
     return [...value];
 }
+function envSecrets(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 8)
+        throw new Error('envSecrets');
+    const result = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !ENV_NAME.test(item) || result.includes(item))
+            throw new Error('envSecrets');
+        result.push(item);
+    }
+    return result;
+}
 function configChanges(value) {
     if (value === undefined)
         return [];
@@ -98,20 +113,22 @@ export async function planLifecycle(input, phase, extra = {}) {
     const staticDefaults = base.configDefaults ? [base.configDefaults] : [];
     if (raw === PHASE_MISSING) {
         const { configDefaults: _ignored, ...rest } = base;
-        return { ...rest, defaults: staticDefaults, requires: [], configChanges: [] };
+        return { ...rest, defaults: staticDefaults, requires: [], configChanges: [], envSecrets: [] };
     }
     let plan;
     let requires;
     let changes;
+    let secrets;
     try {
         plan = object(raw, 'installation plan');
         const allowed = phase === 'planInstall'
-            ? ['directories', 'files', 'entry', 'configDefaults', 'requires']
+            ? ['directories', 'files', 'entry', 'configDefaults', 'requires', 'envSecrets']
             : ['directories', 'files', 'entry', 'configChanges', 'requires'];
         if (Object.keys(plan).some((key) => !allowed.includes(key)))
             throw new Error('keys');
         requires = requirements(plan.requires, plugin.id);
         changes = configChanges(plan.configChanges);
+        secrets = envSecrets(plan.envSecrets);
     }
     catch {
         throw invalidPlan(plugin.id);
@@ -134,7 +151,7 @@ export async function planLifecycle(input, phase, extra = {}) {
             files: dynamic.files.slice(base.files.length),
             directories: plan.directories ?? [],
             ...(plan.entry !== undefined ? { entry: dynamic.entry } : {}),
-        }, plugin.id);
+        }, plugin.id, plugin.hosts);
     }
     catch {
         throw invalidPlan(plugin.id);
@@ -145,6 +162,7 @@ export async function planLifecycle(input, phase, extra = {}) {
         defaults: configDefaults ? [...staticDefaults, configDefaults] : staticDefaults,
         requires,
         configChanges: changes,
+        envSecrets: secrets,
     };
 }
 export async function checkPlugin(input) {

package/dist/plugins-command.d.ts

@@ -0,0 +1,47 @@
+import { type CatalogPackage, type SearchResult } from './catalog.js';
+export interface ListedPackage {
+    readonly id: string | null;
+    readonly package: string;
+    readonly kind: CatalogPackage['kind'];
+    readonly version: string;
+    readonly summary: string;
+    readonly maturity: CatalogPackage['maturity'];
+    readonly provides: readonly string[];
+    readonly install: string;
+    readonly core: string | null;
+    readonly compatible: boolean;
+    readonly installed: string | null;
+    /** With --online: the registry's latest and the highest version for this core. */
+    readonly registry?: {
+        latest: string | null;
+        compatible: string | null;
+    } | 'not-published';
+}
+export declare function pluginsList(root: string, options: {
+    compatible: boolean;
+    online: boolean;
+}): Promise<{
+    source: 'snapshot' | 'registry';
+    coreVersion: string;
+    coreFrom: 'project' | 'catalog';
+    packages: ListedPackage[];
+    warnings: {
+        code: string;
+        message: string;
+    }[];
+}>;
+export declare function pluginsSearch(query: string): Promise<SearchResult>;
+export declare function pluginsInfo(root: string, key: string): Promise<CatalogPackage & {
+    capabilityDetails: Record<string, string>;
+    installed: string | null;
+    compatible: boolean;
+    coreVersion: string;
+}>;
+/** The installed version's AI guide: path relative to the project and its content. */
+export declare function pluginsDoc(root: string, key: string): Promise<{
+    id: string | null;
+    package: string;
+    version: string;
+    path: string;
+    content: string;
+}>;

package/dist/plugins-command.js

@@ -0,0 +1,189 @@
+// `dokebi plugins list|search|info|doc` (D-0065): what Dokebi has, from the catalog snapshot
+// shipped with this CLI, optionally refreshed from the registry; and what it does not have.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import satisfies from 'semver/functions/satisfies.js';
+import { findPackage, loadCatalog, searchCatalog, } from './catalog.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { parseObject } from './filesystem.js';
+import { fetchPackument, highestCompatible } from './registry.js';
+import { installedPath, packageFile } from './workspace.js';
+async function projectFacts(root) {
+    const installed = new Map();
+    let state;
+    try {
+        state = JSON.parse(await readFile(join(root, '.dokebi/state.json'), 'utf8'));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { core: null, installed };
+        throw new CliError('INVALID_STATE', 'Cannot read .dokebi/state.json', { cause: error });
+    }
+    for (const plugin of state.plugins ?? [])
+        installed.set(plugin.packageName, plugin.version);
+    let core = null;
+    for (const name of ['@dokebi/core', '@dokebi/config', '@dokebi/cli']) {
+        try {
+            const pkg = parseObject(await readFile(await packageFile(root, name, 'package.json'), 'utf8'), name);
+            if (typeof pkg.version === 'string') {
+                installed.set(name, pkg.version);
+                if (name === '@dokebi/core')
+                    core = pkg.version;
+            }
+        }
+        catch (error) {
+            if (!isMissing(error) && !(error instanceof CliError))
+                throw error;
+            debug('Package not installed in this project', { package: name });
+        }
+    }
+    return { core, installed };
+}
+function listed(item, facts, core) {
+    return {
+        id: item.id,
+        package: item.package,
+        kind: item.kind,
+        version: item.version,
+        summary: item.summary,
+        maturity: item.maturity,
+        provides: item.provides,
+        install: item.install,
+        core: item.core,
+        compatible: item.core === null || satisfies(core, item.core),
+        installed: facts.installed.get(item.package) ?? null,
+    };
+}
+export async function pluginsList(root, options) {
+    const catalog = await loadCatalog();
+    const facts = await projectFacts(root);
+    const core = facts.core ?? catalog.core.version;
+    let packages = catalog.packages.map((item) => listed(item, facts, core));
+    const warnings = [];
+    let source = 'snapshot';
+    if (options.online) {
+        const offline = [];
+        const queue = [...packages];
+        const refreshed = new Map();
+        const worker = async () => {
+            for (let item = queue.shift(); item; item = queue.shift()) {
+                const found = await fetchPackument(item.package, root);
+                if (found.status === 'offline')
+                    offline.push(item.package);
+                else
+                    refreshed.set(item.package, found.status === 'missing'
+                        ? 'not-published'
+                        : { latest: found.latest, compatible: highestCompatible(found, core) });
+            }
+        };
+        await Promise.all(Array.from({ length: 6 }, worker));
+        packages = packages.map((item) => {
+            const registry = refreshed.get(item.package);
+            if (registry === undefined)
+                return item;
+            return {
+                ...item,
+                registry,
+                compatible: item.compatible && registry !== 'not-published' && registry.compatible !== null,
+            };
+        });
+        if (offline.length)
+            warnings.push({
+                code: 'CATALOG_OFFLINE',
+                message: `The registry did not answer for ${offline.length} packages; their entries come from the snapshot of CLI ${catalog.cli}`,
+            });
+        if (refreshed.size)
+            source = 'registry';
+    }
+    if (options.compatible)
+        packages = packages.filter((item) => item.compatible);
+    return {
+        source,
+        coreVersion: core,
+        coreFrom: facts.core ? 'project' : 'catalog',
+        packages,
+        warnings,
+    };
+}
+export async function pluginsSearch(query) {
+    return searchCatalog(await loadCatalog(), query);
+}
+function unknownPackage(catalog, key) {
+    const search = searchCatalog(catalog, key);
+    return new CliError('UNKNOWN_PLUGIN', `No Dokebi package "${key}"`, {
+        phase: 'arguments',
+        details: {
+            query: key,
+            matches: search.matches.map((item) => item.id ?? item.package),
+            absent: search.absent.map((entry) => ({
+                capability: entry.capability,
+                summary: entry.summary,
+                instead: entry.instead,
+            })),
+            hint: 'npx dokebi plugins search <words> --json',
+        },
+    });
+}
+export async function pluginsInfo(root, key) {
+    const catalog = await loadCatalog();
+    const item = findPackage(catalog, key);
+    if (!item)
+        throw unknownPackage(catalog, key);
+    const facts = await projectFacts(root);
+    const core = facts.core ?? catalog.core.version;
+    return {
+        ...item,
+        capabilityDetails: Object.fromEntries(item.provides.map((name) => [name, catalog.capabilities[name]?.summary ?? ''])),
+        installed: facts.installed.get(item.package) ?? null,
+        compatible: item.core === null || satisfies(core, item.core),
+        coreVersion: core,
+    };
+}
+/** The installed version's AI guide: path relative to the project and its content. */
+export async function pluginsDoc(root, key) {
+    const catalog = await loadCatalog();
+    const item = findPackage(catalog, key);
+    const packageName = item?.package ?? (key.startsWith('@') ? key : undefined);
+    if (!packageName)
+        throw unknownPackage(catalog, key);
+    let pkg;
+    try {
+        pkg = parseObject(await readFile(await packageFile(root, packageName, 'package.json'), 'utf8'), packageName);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        debug('plugins doc: package not installed', {
+            package: packageName,
+            error: describeError(error),
+        });
+        throw new CliError('NOT_INSTALLED', `${packageName} is not installed in this project`, {
+            phase: 'arguments',
+            details: {
+                package: packageName,
+                hint: `npx dokebi add ${packageName} --dry-run --json`,
+                summary: item?.summary ?? null,
+            },
+        });
+    }
+    const manifest = pkg.dokebi;
+    const documentation = typeof manifest?.documentation === 'string' ? manifest.documentation : 'AI.md';
+    const path = `node_modules/${packageName}/${documentation}`;
+    let content;
+    try {
+        content = await readFile(await installedPath(root, path), 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        throw new CliError('DOC_MISSING', `${path} is missing`, { cause: error, details: { path } });
+    }
+    return {
+        id: item?.id ?? null,
+        package: packageName,
+        version: String(pkg.version),
+        path,
+        content,
+    };
+}

package/dist/project-guide.d.ts

@@ -1 +1,36 @@
-export declare const PROJECT_GUIDE = "# Dokebi \uD504\uB85C\uC81D\uD2B8 \uC791\uC5C5 \uC548\uB0B4\n\n\uC124\uCE58\uB41C \uCF54\uC5B4 \uACC4\uC57D\uC740 [\uCF54\uC5B4 AI \uC0AC\uC6A9 \uC548\uB0B4](node_modules/@dokebi/core/AI.md)\uB97C \uC77D\uB294\uB2E4.\n\uD328\uD0A4\uC9C0 \uBC84\uC804\uC740 package.json\uACFC \uC2E4\uC81C node_modules\uB97C \uD568\uAED8 \uD655\uC778\uD55C\uB2E4.\n\n- \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0\uC11C \uC124\uCE58\uB41C CLI\uB85C dokebi inspect --json, dokebi doctor --json\uC744 \uC2E4\uD589\uD55C\uB2E4.\n- inspect\uC5D0 \uB098\uC628 \uD50C\uB7EC\uADF8\uC778 documentation\uACFC optionsSchema\uB97C \uD655\uC778\uD55C\uB2E4.\n- src/main.ts\uB294 \uC0AC\uC6A9\uC790 \uC9C4\uC785\uC810, dokebi.yaml\uC740 \uC0AC\uC6A9\uC790 \uC635\uC158\uC774\uB2E4.\n- \uD3F4\uB354 \uAD6C\uC870(D-0031\u00B7D-0032): src/apps/<\uC571>(\uC571 \uD558\uB098\uC758 app.ts\u00B7routes.ts\u00B7controllers\u00B7models\u00B7views\u00B7sockets), src/shared/modules/<\uBAA8\uB4C8>(\uAE30\uB2A5 \uD558\uB098\uC758 module.ts\u00B7routes.ts\u00B7controllers\u00B7models\u00B7views, dokebi module add\uB85C \uB9CC\uB4E4\uACE0 \uC571\uC758 modules: { '/\uC811\uB450\uC0AC': \uBAA8\uB4C8 }\uB85C \uBD99\uC778\uB2E4), src/shared/models(\uACF5\uD1B5 \uC21C\uC218 \uCF54\uB4DC), src/shared/views(\uACF5\uD1B5 \uB808\uC774\uC544\uC6C3\u00B7\uBD80\uBD84 \uD15C\uD50C\uB9BF), src/infra/<\uC774\uB984>(\uD50C\uB7EC\uADF8\uC778 \uC5F0\uACB0 \uC124\uC815: db/connections.ts, events/types.ts, inertia/shared.ts, web/requires.ts, worker/tasks.ts), src/plugins/<\uC774\uB984>(\uC9C1\uC811 \uB9CC\uB4E0 \uD50C\uB7EC\uADF8\uC778). \uC5C5\uBB34 \uCF54\uB4DC\uB294 apps\u00B7shared/modules\uC5D0\uB9CC, \uD50C\uB7EC\uADF8\uC778 \uC5F0\uACB0 \uCF54\uB4DC\uB294 infra\uC5D0\uB9CC \uB454\uB2E4. \uCEE8\uD2B8\uB864\uB7EC\uB294 \uC571\uC774\uB098 \uBAA8\uB4C8\uC5D0 \uC18D\uD55C\uB2E4.\n- \uC2E4\uC81C dokebi.yaml\uC740 Git\uC5D0 \uB123\uC9C0 \uC54A\uB294\uB2E4. dokebi.example.yaml\uC740 \uBE44\uBC00\uAC12 \uC5C6\uB294 \uCD5C\uCD08 \uC124\uC815 \uACAC\uBCF8\uC774\uB2E4.\n- JSON \uD504\uB85C\uC81D\uD2B8\uB294 core 0.2.x \uC124\uCE58 \uD6C4 dokebi migrate --dry-run\uC73C\uB85C \uC774\uC804 \uACC4\uD68D\uBD80\uD130 \uD655\uC778\uD55C\uB2E4.\n- config\uB294 \uCF54\uC5B4 \uD544\uC218 \uAD6C\uC131\uC73C\uB85C \uC790\uB3D9 \uC124\uCE58\uB418\uBA70 remove\uD560 \uC218 \uC5C6\uB2E4.\n- src/dokebi.generated.ts\uC640 .dokebi/state.json\uC740 \uC9C1\uC811 \uD3B8\uC9D1\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- add\uB294 \uD328\uD0A4\uC9C0 \uC9C0\uC815, upgrade\u00B7remove\uB294 \uD50C\uB7EC\uADF8\uC778 ID\uB97C \uBC1B\uB294\uB2E4. \uBA3C\uC800 --dry-run\uC73C\uB85C \uAC80\uD1A0\uD55C\uB2E4. \uC124\uCE58 \uC804 \uC124\uC815\uC740 add --set path=value\uB85C \uB118\uAE38 \uC218 \uC788\uB2E4.\n- \uD50C\uB7EC\uADF8\uC778\uC774 \uB9CC\uB4E0 \uC9C4\uC785 \uD30C\uC77C(\uC608: src/db/connections.ts)\uC740 \uC0AC\uC6A9\uC790 \uCF54\uB4DC\uB2E4. \uC9C1\uC811 \uACE0\uCE58\uACE0, \uC9C0\uC6B0\uC9C0 \uC54A\uB294\uB2E4.\n- doctor\uB294 \uC790\uB3D9 \uBCF5\uAD6C\uD558\uC9C0 \uC54A\uB294\uB2E4. \uC7A0\uAE08\uC774\uB098 \uBC31\uC5C5\uC744 \uC784\uC758 \uC0AD\uC81C\uD558\uAC70\uB098 \uC2E4\uD328\uB97C \uBB34\uC870\uAC74 \uC7AC\uC2DC\uB3C4\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- src\uC758 .ts\uB294 Node\uAC00 \uD0C0\uC785\uB9CC \uC9C0\uC6B0\uACE0 \uC2E4\uD589\uD55C\uB2E4. \uC0DD\uC131\uC790 \uB9E4\uAC1C\uBCC0\uC218 \uC18D\uC131\u00B7enum\u00B7namespace\uCC98\uB7FC \uC9C0\uC6B8 \uC218 \uC5C6\uB294 \uBB38\uBC95\uC740 \uC4F0\uC9C0 \uC54A\uB294\uB2E4(tsconfig.json\uC758 erasableSyntaxOnly\uAC00 \uD3B8\uC9D1\uAE30\uC640 npx tsc -p tsconfig.json\uC5D0\uC11C \uC54C\uB824 \uC900\uB2E4).\n- \uBCC0\uACBD \uD6C4 npm start\uC640 \uD504\uB85C\uC81D\uD2B8\uBCC4 \uD14C\uC2A4\uD2B8\uB97C \uC2E4\uD589\uD55C\uB2E4.\n";
+import type { PluginManifest } from './manifest.js';
+import type { RequiredPlugin } from './required-plugins.js';
+/** Markers of the CLI-maintained list of installed packages in AGENTS.md (D-0065). */
+export declare const INSTALLED_START = "<!-- dokebi:installed:start -->";
+export declare const INSTALLED_END = "<!-- dokebi:installed:end -->";
+export declare const AGENTS_FILE = "AGENTS.md";
+export declare const CLAUDE_FILE = "CLAUDE.md";
+/** CLAUDE.md of a new project: Claude Code reads AGENTS.md through this import line. */
+export declare const CLAUDE_GUIDE = "@AGENTS.md\n";
+/** One row of the installed list: a package, its version and its AI guide path. */
+export interface InstalledEntry {
+    readonly id: string;
+    readonly packageName: string;
+    readonly version: string;
+    readonly documentation: string | null;
+}
+/** The block between the markers (markers included), rewritten by add, upgrade and remove. */
+export declare function installedBlock(entries: readonly InstalledEntry[]): string;
+/** The rows of the AGENTS.md installed list: core, CLI, required plugins, then plugins. */
+export declare function guideEntries(core: string, required: readonly RequiredPlugin[], plugins: readonly PluginManifest[], cli: string): InstalledEntry[];
+/**
+ * Whether the installed list in an AGENTS.md text was edited by hand (doctor
+ * GUIDE_BLOCK_MODIFIED, D-0072): a line that is not a marker, comment or table line, or rows
+ * whose `id | package | version` differ from `entries`. The core and CLI versions are not
+ * compared (npm can update them before the next add rewrites the block), nor the header,
+ * comment and AI.md path wording (a newer CLI may word them differently). undefined when the
+ * markers are missing (GUIDE_BLOCK_MISSING).
+ */
+export declare function installedBlockEdited(text: string, entries: readonly InstalledEntry[]): boolean | undefined;
+/**
+ * Replaces the block in an AGENTS.md text. Returns undefined when the markers are missing or out
+ * of order (the developer removed them; doctor reports GUIDE_BLOCK_MISSING and the file stays).
+ */
+export declare function replaceInstalledBlock(text: string, block: string): string | undefined;
+/** AGENTS.md of a new project (D-0065 skeleton): ask first, use the catalog, verify last. */
+export declare function projectGuide(entries: readonly InstalledEntry[]): string;

package/dist/project-guide.js

@@ -1,19 +1,142 @@
-export const PROJECT_GUIDE = `# Dokebi 프로젝트 작업 안내
-
-설치된 코어 계약은 [코어 AI 사용 안내](node_modules/@dokebi/core/AI.md)를 읽는다.
-패키지 버전은 package.json과 실제 node_modules를 함께 확인한다.
-
-- 프로젝트 루트에서 설치된 CLI로 dokebi inspect --json, dokebi doctor --json을 실행한다.
-- inspect에 나온 플러그인 documentation과 optionsSchema를 확인한다.
-- src/main.ts는 사용자 진입점, dokebi.yaml은 사용자 옵션이다.
-- 폴더 구조(D-0031·D-0032): src/apps/<앱>(앱 하나의 app.ts·routes.ts·controllers·models·views·sockets), src/shared/modules/<모듈>(기능 하나의 module.ts·routes.ts·controllers·models·views, dokebi module add로 만들고 앱의 modules: { '/접두사': 모듈 }로 붙인다), src/shared/models(공통 순수 코드), src/shared/views(공통 레이아웃·부분 템플릿), src/infra/<이름>(플러그인 연결 설정: db/connections.ts, events/types.ts, inertia/shared.ts, web/requires.ts, worker/tasks.ts), src/plugins/<이름>(직접 만든 플러그인). 업무 코드는 apps·shared/modules에만, 플러그인 연결 코드는 infra에만 둔다. 컨트롤러는 앱이나 모듈에 속한다.
-- 실제 dokebi.yaml은 Git에 넣지 않는다. dokebi.example.yaml은 비밀값 없는 최초 설정 견본이다.
-- JSON 프로젝트는 core 0.2.x 설치 후 dokebi migrate --dry-run으로 이전 계획부터 확인한다.
-- config는 코어 필수 구성으로 자동 설치되며 remove할 수 없다.
-- src/dokebi.generated.ts와 .dokebi/state.json은 직접 편집하지 않는다.
-- add는 패키지 지정, upgrade·remove는 플러그인 ID를 받는다. 먼저 --dry-run으로 검토한다. 설치 전 설정은 add --set path=value로 넘길 수 있다.
-- 플러그인이 만든 진입 파일(예: src/db/connections.ts)은 사용자 코드다. 직접 고치고, 지우지 않는다.
-- doctor는 자동 복구하지 않는다. 잠금이나 백업을 임의 삭제하거나 실패를 무조건 재시도하지 않는다.
-- src의 .ts는 Node가 타입만 지우고 실행한다. 생성자 매개변수 속성·enum·namespace처럼 지울 수 없는 문법은 쓰지 않는다(tsconfig.json의 erasableSyntaxOnly가 편집기와 npx tsc -p tsconfig.json에서 알려 준다).
-- 변경 후 npm start와 프로젝트별 테스트를 실행한다.
+/** Markers of the CLI-maintained list of installed packages in AGENTS.md (D-0065). */
+export const INSTALLED_START = '<!-- dokebi:installed:start -->';
+export const INSTALLED_END = '<!-- dokebi:installed:end -->';
+export const AGENTS_FILE = 'AGENTS.md';
+export const CLAUDE_FILE = 'CLAUDE.md';
+/** CLAUDE.md of a new project: Claude Code reads AGENTS.md through this import line. */
+export const CLAUDE_GUIDE = '@AGENTS.md\n';
+/** The block between the markers (markers included), rewritten by add, upgrade and remove. */
+export function installedBlock(entries) {
+    const rows = entries.map((entry) => `| ${entry.id} | ${entry.packageName} | ${entry.version} | ${entry.documentation ? `node_modules/${entry.packageName}/${entry.documentation}` : '-'} |`);
+    return [
+        INSTALLED_START,
+        '<!-- dokebi add, upgrade and remove rewrite this block in the same transaction. Do not edit between these two markers by hand. -->',
+        '| Name | Package | Version | AI guide (read first) |',
+        '|---|---|---|---|',
+        ...rows,
+        INSTALLED_END,
+    ].join('\n');
+}
+/** The rows of the AGENTS.md installed list: core, CLI, required plugins, then plugins. */
+export function guideEntries(core, required, plugins, cli) {
+    return [
+        { id: 'core', packageName: '@dokebi/core', version: core, documentation: 'AI.md' },
+        { id: 'cli', packageName: '@dokebi/cli', version: cli, documentation: 'AI.md' },
+        ...required.map((plugin) => ({
+            id: plugin.id,
+            packageName: plugin.packageName,
+            version: plugin.version,
+            documentation: 'AI.md',
+        })),
+        ...plugins.map((plugin) => ({
+            id: plugin.id,
+            packageName: plugin.packageName,
+            version: plugin.version,
+            documentation: plugin.documentation ?? null,
+        })),
+    ];
+}
+/**
+ * Whether the installed list in an AGENTS.md text was edited by hand (doctor
+ * GUIDE_BLOCK_MODIFIED, D-0072): a line that is not a marker, comment or table line, or rows
+ * whose `id | package | version` differ from `entries`. The core and CLI versions are not
+ * compared (npm can update them before the next add rewrites the block), nor the header,
+ * comment and AI.md path wording (a newer CLI may word them differently). undefined when the
+ * markers are missing (GUIDE_BLOCK_MISSING).
+ */
+export function installedBlockEdited(text, entries) {
+    const start = text.indexOf(INSTALLED_START);
+    const end = text.indexOf(INSTALLED_END);
+    if (start === -1 || end === -1 || end < start)
+        return undefined;
+    const lines = text
+        .slice(start + INSTALLED_START.length, end)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.some((line) => !line.startsWith('|') && !/^<!--.*-->$/.test(line)))
+        return true;
+    const key = (id, name, version) => `${id}|${name}|${id === 'core' || id === 'cli' ? '*' : version}`;
+    const table = lines.filter((line) => line.startsWith('|'));
+    const rows = table
+        .slice(1)
+        .filter((line) => !/^\|[\s|:-]*$/.test(line))
+        .map((line) => {
+        const cells = line.split('|').map((cell) => cell.trim());
+        return key(cells[1] ?? '', cells[2] ?? '', cells[3] ?? '');
+    });
+    const wanted = entries.map((entry) => key(entry.id, entry.packageName, entry.version));
+    return rows.length !== wanted.length || rows.some((row, index) => row !== wanted[index]);
+}
+/**
+ * Replaces the block in an AGENTS.md text. Returns undefined when the markers are missing or out
+ * of order (the developer removed them; doctor reports GUIDE_BLOCK_MISSING and the file stays).
+ */
+export function replaceInstalledBlock(text, block) {
+    const start = text.indexOf(INSTALLED_START);
+    const end = text.indexOf(INSTALLED_END);
+    if (start === -1 || end === -1 || end < start)
+        return undefined;
+    return text.slice(0, start) + block + text.slice(end + INSTALLED_END.length);
+}
+/** AGENTS.md of a new project (D-0065 skeleton): ask first, use the catalog, verify last. */
+export function projectGuide(entries) {
+    return `# Working on this Dokebi project (for AI agents)
+
+This project is built with the Dokebi framework. The CLI is the \`@dokebi/cli\` installed in this project; run it from the project root as \`npx dokebi …\`.
+The npm package named \`dokebi\` is not this CLI: never run \`npx -y dokebi\` (if \`node_modules/@dokebi/cli\` is missing, run \`npm install\`; outside a project use \`npx -y @dokebi/cli …\`).
+Run the command-line tools installed in this project by their bin names from the project root: \`npx dokebi …\` and, with @dokebi/migrate, \`npx dokebi-migrate …\`. Never run a file inside \`node_modules/*/dist/\` and do not use \`npm exec --package …\` for them.
+
+## 0. First
+
+1. \`npx dokebi guide --json\`: the steps from a one-line request to a verified app (this document in short) and every command.
+2. \`npx dokebi inspect --json\`: installed plugins, versions, option schemas and diagnostics.
+3. Read the AI guide of every package in the "Installed packages" table below (the AI.md of the installed version). Read a plugin's AI.md before you write code with it (\`npx dokebi plugins doc <id> --json\`). The installed AI.md is right where older documents on the internet or your memory disagree.
+
+## 1. Do not decide alone: ask first
+
+- Find the recipe for the request: \`npx dokebi recipe list --json\` (a blog is \`blog\`, a JSON API is \`api\`).
+- When answers are missing, \`npx dokebi recipe <name> --json\` installs nothing and returns \`status: "needs-answers"\`, \`waitForUser: true\` and \`questions[]\` (options, pros and cons, what each installs, what it needs, the default and its reason), with the error \`ANSWERS_REQUIRED\` (exit 2).
+- Choices such as the view (ejs, inertia-vue, inertia-vue-ssr), the database (postgres, mysql, mariadb, mongodb, none), the development database (docker, url) and an admin area are **the user's: show them as questions and get the answers**. Tell the user that an option with \`available: false\` (absent) does not exist; do not offer it.
+- **Ask these questions and end your turn; do not run recipe/add/config until the user answers. Only use \`--defaults\` if the user said to decide.** After showing the questions, do not go on installing ("I will continue with the defaults while you choose").
+- Use \`--defaults\` only when the user left the choice to you ("you decide"). Then report the chosen values and their \`defaultReason\` to the user when you are done (\`verify\` returns them as \`tellUser\`, see 3).
+- When the user answers, pass the answers as flags and add \`--answers-from user\`. Look at the plan first with \`--dry-run --json\` (\`plan.steps\`, \`preflight\`), then run it (applying without \`--answers-from user\` or \`--defaults\` fails with \`ANSWERS_SOURCE_REQUIRED\`). Tell the user the \`report\` of the result (where the answers came from, the defaults, and what to know, such as no CSRF protection). On a preflight error (\`DOCKER_MISSING\`, \`PORT_IN_USE\`) ask the user; never switch to another database or port behind their back.
+
+## 2. Plugins
+
+- What exists: \`npx dokebi plugins list --json\`; find: \`npx dokebi plugins search <word|capability> --json\`; details: \`npx dokebi plugins info <id> --json\`.
+- The \`absent\` entries of a search (for example auth, csrf, upload, mail, markdown, sqlite, React) are **features Dokebi does not have**. Never invent a plugin, flag or API for them: build them in app code as their \`instead\` says, or tell the user.
+- Install with \`npx dokebi add <package> --dry-run --json\` first, then the same command without \`--dry-run\`. Without a version, add picks the newest version that fits this core (\`resolved\`).
+- Never install or run a package outside \`@dokebi/\` (someone else's package, \`THIRD_PARTY_PACKAGE\`) without the permission of the user.
+- Never pass a secret (password, token, connection URL) with \`--set\` or \`config set\` (the shell history keeps it). Write it into dokebi.yaml yourself, use \`npx dokebi config secret <id>.<path>\` for a generated one, or use the value \`npx dokebi dev-infra\` generated.
+- Secrets a plugin reads from an environment variable (for example \`DOKEBI_SESSION_SECRETS\` of @dokebi/session) live in \`.env\`: \`npx dokebi add\` generates the ones a plugin declares (\`generatedSecrets\` names them), and \`npx dokebi dev\`, \`start\` and \`verify\` pass \`.env\` to the app (a variable set in the environment wins). Do not wrap the CLI in \`node --env-file\`, never commit \`.env\` and never print its values.
+
+## 3. Before you say it is done
+
+- \`npx dokebi check --json\`: the code convention check (empty \`catch\` and \`.catch(() => {})\`, a promise without await, syntax Node cannot strip (enum, parameter properties, namespaces with values, decorators), private paths such as \`@dokebi/*/dist\` and \`@dokebi/*\` packages that are not installed, edited generated files, secrets that would be committed). Every problem has \`file\`, \`line\` and \`fix\`: fix it as \`fix\` says. Only an empty catch or a background promise that is really intended gets a \`// dokebi-check: allow <rule> <reason>\` comment.
+- Say "done" only after \`npx dokebi verify --json\` returns \`ok: true\` (doctor, check, typecheck, build, start, HTTP checks, stop).
+- **Your final message to the user must include verify's \`tellUser\` lines**, word for word: the choices of the recipe and who made them (a default with its reason) and what to know, such as no CSRF protection for HTML forms. They come from \`.dokebi/recipe.json\`, which \`recipe\` writes; do not edit it.
+- When \`ok: false\`, fix the failed items of \`checks[]\` (\`code\`, \`details\`) and run verify again. Never hide a failure or turn a check off.
+
+## 4. Structure rules
+
+- \`src/main.ts\` is the user entry point, \`dokebi.yaml\` holds the real settings of this machine (kept out of Git), and \`dokebi.example.yaml\` is a sample without secrets.
+- Folders (D-0031, D-0032): \`src/apps/<app>\` (one app: app.ts, routes.ts, controllers, models, views), \`src/shared/modules/<module>\` (one feature; create it with \`npx dokebi module add\` and attach it in the app with \`modules: { '/prefix': module }\`), \`src/shared/models\` and \`src/shared/views\` (shared code), \`src/infra/<name>\` (plugin connection code, for example \`src/infra/db/connections.ts\`), \`src/plugins/<name>\` (your own plugins). Business code lives only in apps and shared/modules.
+- **Files the CLI rewrites** are only \`src/dokebi.generated.ts\`, \`.dokebi/state.json\` and the part of this file between the \`dokebi:installed\` markers. Never edit them by hand; change them with commands (\`dokebi check\` reports \`generated-file\`).
+- **Every other file the CLI or a plugin created is user code**: the shared layout and views (\`src/shared/views/layouts/main.ejs\` and others), entry files (for example \`src/infra/db/connections.ts\`, \`src/infra/web/extension.ts\`), and the app and module files \`app add\` and \`module add\` create (app.ts, routes.ts, controllers, models, views and the examples \`items.ts\`, \`summary.ts\`, \`site.ts\`). **Edit them where they are** (do not move or copy them). doctor does not warn about them, and upgrade does not overwrite an edited one (the new template location is in \`preservedDetails\`).
+- Node runs the .ts files in \`src\` by stripping their types. Do not use syntax that cannot be stripped, such as constructor parameter properties, enum or namespace (\`npm run typecheck\` reports it). Do not run \`npx tsc\` (the npm package named tsc is not TypeScript).
+- doctor repairs nothing. Never delete the lock (\`.dokebi/lock\`) or a backup, and never blindly re-run a failed command.
+- config (\`@dokebi/config\`) is a required part of the core and cannot be removed.
+
+## 5. Errors and forms (D-0074)
+
+- **Refuse input with \`throw validationError({ field: 'message' })\`** (\`import { validationError } from '@dokebi/web'\`), not with your own \`reply.code(422).send(...)\`. Clients then get exactly what a refused route schema gives them: 422 \`VALIDATION_FAILED\` with \`fields: [{ field, message }]\` and \`errors: { field: message }\`. Other refusals throw a \`DokebiError\` with a \`status\` (403, 404, 409…).
+- **JSON or HTML is decided for you**: Inertia requests, \`fetch\`/XHR, Bearer API clients and JSON bodies get JSON errors; only plain browser pages (a navigation, an HTML form post) get an HTML page. Read errors from the JSON (\`body.errors.name\`); do not parse HTML.
+- **Inertia forms** (\`useForm().post/put/patch/delete\`, \`router.post/…\`): pass \`only\` with the props the submit changes, for example \`form.post(url, { only: ['items'] })\`. With @dokebi/session a validation error goes back (303) with the messages in \`form.errors.<field>\` (\`errors\` always comes along); without \`only\` the GET after the redirect sends every prop of the page again. \`npx dokebi check\` warns about a submit without \`only\` (\`inertia-form-only\`).
+- **Error pages**: an EJS app shows \`views/<template>/errors/<status>.ejs\` (then \`errors/error.ejs\`) for browser pages, with \`status\`, \`error\`, \`message\`, \`hint\` and \`fields\`; an Inertia app may set \`inertia: { errorPage: 'Error' }\` to render its \`Error\` page component.
+
+## Installed packages
+
+${installedBlock(entries)}
 `;
+}

package/dist/project-inspector.d.ts

@@ -10,7 +10,17 @@ export interface Diagnostic {
     /** A command that resolves the diagnostic. */
     hint?: string;
 }
+/** The short form of an inspection (first in the result; the default human output). */
+export interface InspectionSummary {
+    healthy: boolean;
+    errors: number;
+    warnings: number;
+    plugins: number;
+    /** Diagnostic code → how often it occurs. */
+    codes: Record<string, number>;
+}
 export interface Inspection {
+    summary: InspectionSummary;
     root: string;
     healthy: boolean;
     coreVersion: string | null;

package/dist/project-inspector.js

@@ -10,6 +10,7 @@ import { orderPlugins, readManifest } from './manifest.js';
 import { dependencyMap, validateProjectPackage } from './npm-client.js';
 import { checkPlugin } from './plugin-lifecycle.js';
 import { PluginOptionsValidator } from './plugin-options.js';
+import { AGENTS_FILE, guideEntries, INSTALLED_END, INSTALLED_START, installedBlockEdited, } from './project-guide.js';
 import { readState } from './project-state.js';
 import { readRequiredPlugins } from './required-plugins.js';
 import { installedPath } from './workspace.js';
@@ -19,6 +20,7 @@ export class ProjectInspector {
     async inspect(directory, settings = {}) {
         const root = await realpath(directory);
         const result = {
+            summary: { healthy: false, errors: 0, warnings: 0, plugins: 0, codes: {} },
             root,
             healthy: false,
             coreVersion: null,
@@ -157,7 +159,7 @@ export class ProjectInspector {
                     if (present === false)
                         issue('ENTRY_MISSING', entry, plugin.id);
                     // Installed before the D-0031 layout: it keeps working where it is.
-                    if (legacyLayout(entry, plugin.id))
+                    if (legacyLayout(entry, plugin.hosts))
                         issue('LEGACY_LAYOUT', entry, plugin.id, 'warning');
                 }
                 if (settings.runChecks && installed && config && pkg) {
@@ -193,6 +195,7 @@ export class ProjectInspector {
                                     code: item.code,
                                     ...(item.optionPath ? { optionPath: item.optionPath } : {}),
                                 },
+                                ...(item.hint ? { hint: item.hint } : {}),
                             });
                     }
                 }
@@ -209,10 +212,22 @@ export class ProjectInspector {
             }
             if (core)
                 await check('.dokebi/state.json', async () => orderPlugins(state.plugins, core, result.requiredPlugins));
+            // D-0065 §11: only CLI-owned files (`owner: 'cli'`, regenerated by the CLI or a plugin) are
+            // diagnosed when edited. Scaffolds written for the developer (`owner: 'user'`: layouts,
+            // views, examples, entry files) are expected to change; upgrade keeps an edited copy.
+            const entries = new Set(Object.values(state.installations).flatMap((item) => (item.entry ? [item.entry] : [])));
             for (const [path, owned] of Object.entries(state.files)) {
+                if (owned.owner !== 'cli' || entries.has(path))
+                    continue;
                 const actual = await check(path, async () => fingerprint(await securePath(root, path)));
                 if (actual !== owned.hash)
-                    issue('MODIFIED_TEMPLATE', path, null, 'warning');
+                    result.diagnostics.push({
+                        code: 'MODIFIED_TEMPLATE',
+                        severity: 'warning',
+                        path,
+                        plugin: owned.owners[0] ?? null,
+                        hint: `${path} is regenerated by ${owned.owners.join(', ')} (owner: cli); move your changes to a user-owned file, or restore it`,
+                    });
             }
         }
         for (const [path, expected] of originals) {
@@ -222,6 +237,30 @@ export class ProjectInspector {
                 return true;
             });
         }
+        // D-0065: AGENTS.md carries the CLI-maintained installed list between two markers.
+        await check(AGENTS_FILE, async () => {
+            const path = await securePath(root, AGENTS_FILE);
+            const text = (await exists(path)) ? await readFile(path, 'utf8') : null;
+            if (text === null || !text.includes(INSTALLED_START) || !text.includes(INSTALLED_END))
+                result.diagnostics.push({
+                    code: 'GUIDE_BLOCK_MISSING',
+                    severity: 'warning',
+                    path: AGENTS_FILE,
+                    plugin: null,
+                    hint: `put the lines ${INSTALLED_START} and ${INSTALLED_END} in AGENTS.md; the next add, upgrade or remove fills the list between them`,
+                });
+            // D-0072: a hand edit between the markers is lost on the next add, upgrade or remove.
+            else if (state &&
+                installedBlockEdited(text, guideEntries('*', result.requiredPlugins, state.plugins, '*')))
+                result.diagnostics.push({
+                    code: 'GUIDE_BLOCK_MODIFIED',
+                    severity: 'warning',
+                    path: AGENTS_FILE,
+                    plugin: null,
+                    hint: `move notes outside ${INSTALLED_START} … ${INSTALLED_END} and restore the rows (one per installed package: npx dokebi inspect --json); add, upgrade and remove rewrite them`,
+                });
+            return true;
+        });
         await check('.dokebi/lock', async () => {
             if ((await exists(await securePath(root, '.dokebi/lock'))) &&
                 !result.diagnostics.some((item) => item.code === 'PROJECT_LOCKED'))
@@ -229,6 +268,16 @@ export class ProjectInspector {
             return true;
         });
         result.healthy = !result.diagnostics.some((item) => item.severity === 'error');
+        const codes = {};
+        for (const item of result.diagnostics)
+            codes[item.code] = (codes[item.code] ?? 0) + 1;
+        result.summary = {
+            healthy: result.healthy,
+            errors: result.diagnostics.filter((item) => item.severity === 'error').length,
+            warnings: result.diagnostics.filter((item) => item.severity === 'warning').length,
+            plugins: result.plugins.length,
+            codes,
+        };
         return result;
     }
 }