catui-agent 1.0.0-beta.0

package/dist/core/platform/utils/shell.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Get shell configuration based on platform.
+ * Resolution order:
+ * 1. User-specified shellPath in settings.json
+ * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 3. On Unix: /bin/bash, then bash on PATH, then fallback to sh
+ */
+export declare function getShellConfig(): {
+    shell: string;
+    args: string[];
+};
+export declare function getShellEnv(): NodeJS.ProcessEnv;
+/**
+ * Sanitize binary output for display/storage.
+ * Removes characters that crash string-width or cause display issues:
+ * - Control characters (except tab, newline, carriage return)
+ * - Lone surrogates
+ * - Unicode Format characters (crash string-width due to a bug)
+ * - Characters with undefined code points
+ */
+export declare function sanitizeBinaryOutput(str: string): string;
+/**
+ * Kill a process and all its children (cross-platform)
+ */
+export declare function killProcessTree(pid: number): void;

package/dist/core/platform/utils/shell.js

@@ -0,0 +1,9 @@
+var g=Object.defineProperty;var s=(t,e)=>g(t,"name",{value:e,configurable:!0});import{existsSync as l}from"node:fs";import{delimiter as f}from"node:path";import{spawn as m,spawnSync as u}from"child_process";import{getBinDir as P,getSettingsPath as p}from"../../../config.js";import{SettingsManager as b}from"../config/settings-manager.js";let n=null;function d(){if(process.platform==="win32"){try{const t=u("where",["bash.exe"],{encoding:"utf-8",timeout:5e3});if(t.status===0&&t.stdout){const e=t.stdout.trim().split(/\r?\n/)[0];if(e&&l(e))return e}}catch{}return null}try{const t=u("which",["bash"],{encoding:"utf-8",timeout:5e3});if(t.status===0&&t.stdout){const e=t.stdout.trim().split(/\r?\n/)[0];if(e)return e}}catch{}return null}s(d,"findBashOnPath");function k(){if(n)return n;const e=b.create().getShellPath();if(e){if(l(e))return n={shell:e,args:["-c"]},n;throw new Error(`Custom shell path not found: ${e}
+Please update shellPath in ${p()}`)}if(process.platform==="win32"){const i=[],h=process.env.ProgramFiles;h&&i.push(`${h}\\Git\\bin\\bash.exe`);const o=process.env["ProgramFiles(x86)"];o&&i.push(`${o}\\Git\\bin\\bash.exe`);for(const c of i)if(l(c))return n={shell:c,args:["-c"]},n;const a=d();if(a)return n={shell:a,args:["-c"]},n;throw new Error(`No bash shell found. Options:
+  1. Install Git for Windows: https://git-scm.com/download/win
+  2. Add your bash to PATH (Cygwin, MSYS2, etc.)
+  3. Set shellPath in ${p()}
+
+Searched Git Bash in:
+${i.map(c=>`  ${c}`).join(`
+`)}`)}if(l("/bin/bash"))return n={shell:"/bin/bash",args:["-c"]},n;const r=d();return r?(n={shell:r,args:["-c"]},n):(n={shell:"sh",args:["-c"]},n)}s(k,"getShellConfig");function v(){const t=P(),e=Object.keys(process.env).find(a=>a.toLowerCase()==="path")??"PATH",r=process.env[e]??"",o=r.split(f).filter(Boolean).includes(t)?r:[t,r].filter(Boolean).join(f);return{...process.env,[e]:o}}s(v,"getShellEnv");function G(t){return Array.from(t).filter(e=>{const r=e.codePointAt(0);return r===void 0?!1:r===9||r===10||r===13?!0:!(r<=31||r>=65529&&r<=65531)}).join("")}s(G,"sanitizeBinaryOutput");function I(t){if(process.platform==="win32")try{m("taskkill",["/F","/T","/PID",String(t)],{stdio:"ignore",detached:!0})}catch{}else try{process.kill(-t,"SIGKILL")}catch{try{process.kill(t,"SIGKILL")}catch{}}}s(I,"killProcessTree");export{k as getShellConfig,v as getShellEnv,I as killProcessTree,G as sanitizeBinaryOutput};

package/dist/core/platform/utils/sleep.d.ts

@@ -0,0 +1,7 @@
+/**
+ * [WHO]: sleep()
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/runtime/agent-session.ts
+ * [HERE]: core/platform/utils/sleep.ts - sleep helper that respects abort signal; cleans the abort listener on both resolve and reject so repeated sleeps against the same long-lived signal do not stack listeners (Node fires MaxListenersExceededWarning at 11)
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/core/platform/utils/sleep.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var t=(r,e)=>i(r,"name",{value:e,configurable:!0});function m(r,e){return new Promise((u,o)=>{if(e?.aborted){o(new Error("Aborted"));return}const n=t(()=>{clearTimeout(b),o(new Error("Aborted"))},"onAbort"),b=setTimeout(()=>{e?.removeEventListener("abort",n),u()},r);e?.addEventListener("abort",n,{once:!0})})}t(m,"sleep");export{m as sleep};

package/dist/core/platform/utils/tools-manager.d.ts

@@ -0,0 +1,19 @@
+export declare function getToolPath(tool: "fd" | "rg"): string | null;
+export declare function hasTool(tool: "fd" | "rg"): boolean;
+export declare function ensureTool(tool: "fd" | "rg", silent?: boolean): Promise<string | undefined>;
+export declare function prewarmTool(tool: "fd" | "rg"): void;
+/**
+ * Clear the tool check cache. Useful for forcing a re-check of tool availability.
+ */
+export declare function clearToolCheckCache(): void;
+/**
+ * Get tool check cache stats (for debugging)
+ */
+export declare function getToolCheckCacheStats(): {
+    size: number;
+    inFlight: string[];
+    entries: Array<{
+        tool: string;
+        path: string | null;
+    }>;
+};

package/dist/core/platform/utils/tools-manager.js

@@ -0,0 +1 @@
+var C=Object.defineProperty;var i=(r,e)=>C(r,"name",{value:e,configurable:!0});import d from"chalk";import{spawnSync as N}from"child_process";import F from"extract-zip";import{chmodSync as M,createWriteStream as P,existsSync as _,mkdirSync as b,readdirSync as z,renameSync as I,rmSync as E}from"fs";import{arch as L,platform as $}from"os";import{join as f}from"path";import{Readable as D}from"stream";import{pipeline as U}from"stream/promises";import{APP_NAME as B,getBinDir as W}from"../../../config.js";const m=W(),c=new Map,p=new Map,T=12e4;function O(){const r=process.env.CATUI_TOOLS_DOWNLOAD_TIMEOUT_MS??process.env.NANOPENCIL_TOOLS_DOWNLOAD_TIMEOUT_MS;if(r===void 0||r==="")return T;const e=Number.parseInt(r,10);return Number.isFinite(e)&&e>0?e:T}i(O,"getNetworkTimeoutMs");function R(){const r=process.env.CATUI_OFFLINE??process.env.NANOPENCIL_OFFLINE;return r?r==="1"||r.toLowerCase()==="true"||r.toLowerCase()==="yes":!1}i(R,"isOfflineModeEnabled");const x={fd:{name:"fd",repo:"sharkdp/fd",binaryName:"fd",tagPrefix:"v",getAssetName:i((r,e,n)=>e==="darwin"?`fd-v${r}-${n==="arm64"?"aarch64":"x86_64"}-apple-darwin.tar.gz`:e==="linux"?`fd-v${r}-${n==="arm64"?"aarch64":"x86_64"}-unknown-linux-gnu.tar.gz`:e==="win32"?`fd-v${r}-${n==="arm64"?"aarch64":"x86_64"}-pc-windows-msvc.zip`:null,"getAssetName")},rg:{name:"ripgrep",repo:"BurntSushi/ripgrep",binaryName:"rg",tagPrefix:"",getAssetName:i((r,e,n)=>e==="darwin"?`ripgrep-${r}-${n==="arm64"?"aarch64":"x86_64"}-apple-darwin.tar.gz`:e==="linux"?n==="arm64"?`ripgrep-${r}-aarch64-unknown-linux-gnu.tar.gz`:`ripgrep-${r}-x86_64-unknown-linux-musl.tar.gz`:e==="win32"?`ripgrep-${r}-${n==="arm64"?"aarch64":"x86_64"}-pc-windows-msvc.zip`:null,"getAssetName")}};function j(r){try{const e=N(r,["--version"],{stdio:"pipe"});return e.error===void 0||e.error===null}catch{return!1}}i(j,"commandExists");function A(r){const e=x[r];if(!e)return null;if(c.has(r))return c.get(r)??null;const n=f(m,e.binaryName+($()==="win32"?".exe":""));return _(n)?(c.set(r,n),n):j(e.binaryName)?(c.set(r,e.binaryName),e.binaryName):(c.set(r,null),null)}i(A,"getToolPath");function sr(r){return A(r)!==null}i(sr,"hasTool");async function G(r){const e=O(),n=await fetch(`https://api.github.com/repos/${r}/releases/latest`,{headers:{"User-Agent":`${B}-coding-agent`},signal:AbortSignal.timeout(e)});if(!n.ok)throw new Error(`GitHub API error: ${n.status}`);return(await n.json()).tag_name.replace(/^v/,"")}i(G,"getLatestVersion");async function K(r,e){const n=O(),t=await fetch(r,{signal:AbortSignal.timeout(n)});if(!t.ok)throw new Error(`Failed to download: ${t.status}`);if(!t.body)throw new Error("No response body");const s=P(e);await U(D.fromWeb(t.body),s)}i(K,"downloadFile");function H(r,e){const n=[r];for(;n.length>0;){const t=n.pop();if(!t)continue;const s=z(t,{withFileTypes:!0});for(const o of s){const a=f(t,o.name);if(o.isFile()&&o.name===e)return a;o.isDirectory()&&n.push(a)}}return null}i(H,"findBinaryRecursively");async function V(r){const e=x[r];if(!e)throw new Error(`Unknown tool: ${r}`);const n=$(),t=L(),s=await G(e.repo),o=e.getAssetName(s,n,t);if(!o)throw new Error(`Unsupported platform: ${n}/${t}`);b(m,{recursive:!0});const a=`https://github.com/${e.repo}/releases/download/${e.tagPrefix}${s}/${o}`,g=f(m,o),S=n==="win32"?".exe":"",y=f(m,e.binaryName+S);await K(a,g);const u=f(m,`extract_tmp_${e.binaryName}_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2,10)}`);b(u,{recursive:!0});try{if(o.endsWith(".tar.gz")){const l=N("tar",["xzf",g,"-C",u],{stdio:"pipe"});if(l.error||l.status!==0){const v=l.error?.message??l.stderr?.toString().trim()??"unknown error";throw new Error(`Failed to extract ${o}: ${v}`)}}else if(o.endsWith(".zip"))await F(g,{dir:u});else throw new Error(`Unsupported archive format: ${o}`);const h=e.binaryName+S,k=f(u,o.replace(/\.(tar\.gz|zip)$/,""));let w=[f(k,h),f(u,h)].find(l=>_(l));if(w||(w=H(u,h)??void 0),w)I(w,y);else throw new Error(`Binary not found in archive: expected ${h} under ${u}`);n!=="win32"&&M(y,493)}finally{E(g,{force:!0}),E(u,{recursive:!0,force:!0})}return y}i(V,"downloadTool");const X={fd:"fd",rg:"ripgrep"};async function Z(r,e=!1){const n=A(r);if(n)return n;const t=p.get(r);if(t)return t;const s=x[r];if(!s)return;if(R()){e||console.log(d.yellow(`${s.name} not found. Offline mode enabled, skipping download.`));return}if($()==="android"){const a=X[r]??r;e||console.log(d.yellow(`${s.name} not found. Install with: pkg install ${a}`));return}e||console.log(d.dim(`${s.name} not found. Downloading...`));const o=(async()=>{try{const a=await V(r);return c.set(r,a),e||console.log(d.dim(`${s.name} installed to ${a}`)),a}catch(a){e||console.log(d.yellow(`Failed to download ${s.name}: ${a instanceof Error?a.message:a}`));return}finally{p.delete(r)}})();return p.set(r,o),o}i(Z,"ensureTool");function cr(r){Z(r,!0)}i(cr,"prewarmTool");function ur(){c.clear(),p.clear()}i(ur,"clearToolCheckCache");function fr(){return{size:c.size,inFlight:Array.from(p.keys()),entries:Array.from(c.entries()).map(([r,e])=>({tool:r,path:e}))}}i(fr,"getToolCheckCacheStats");export{ur as clearToolCheckCache,Z as ensureTool,fr as getToolCheckCacheStats,A as getToolPath,sr as hasTool,cr as prewarmTool};

package/dist/core/prompt/prompt-templates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Represents a prompt template loaded from a markdown file
+ */
+export interface PromptTemplate {
+    name: string;
+    description: string;
+    content: string;
+    source: string;
+    filePath: string;
+}
+/**
+ * Parse command arguments respecting quoted strings (bash-style)
+ * Returns array of arguments
+ */
+export declare function parseCommandArgs(argsString: string): string[];
+/**
+ * Substitute argument placeholders in template content
+ * Supports:
+ * - $1, $2, ... for positional args
+ * - $@ and $ARGUMENTS for all args
+ * - ${@:N} for args from Nth onwards (bash-style slicing)
+ * - ${@:N:L} for L args starting from Nth
+ *
+ * Note: Replacement happens on the template string only. Argument values
+ * containing patterns like $1, $@, or $ARGUMENTS are NOT recursively substituted.
+ */
+export declare function substituteArgs(content: string, args: string[]): string;
+export interface LoadPromptTemplatesOptions {
+    /** Working directory for project-local templates. Default: process.cwd() */
+    cwd?: string;
+    /** Agent config directory for global templates. Default: from getPromptsDir() */
+    agentDir?: string;
+    /** Explicit prompt template paths (files or directories) */
+    promptPaths?: string[];
+    /** Include default prompt directories. Default: true */
+    includeDefaults?: boolean;
+}
+/**
+ * Load all prompt templates from:
+ * 1. Global: agentDir/prompts/
+ * 2. Project: cwd/{CONFIG_DIR_NAME}/prompts/
+ * 3. Explicit prompt paths
+ */
+export declare function loadPromptTemplates(options?: LoadPromptTemplatesOptions): PromptTemplate[];
+/**
+ * Expand a prompt template if it matches a template name.
+ * Returns the expanded content or the original text if not a template.
+ */
+export declare function expandPromptTemplate(text: string, templates: PromptTemplate[]): string;

package/dist/core/prompt/prompt-templates.js

@@ -0,0 +1,2 @@
+var W=Object.defineProperty;var a=(t,r)=>W(t,"name",{value:r,configurable:!0});import{existsSync as F,readdirSync as w,readFileSync as T,statSync as $}from"fs";import{homedir as D}from"os";import{basename as j,isAbsolute as x,join as f,resolve as h,sep as A}from"path";import{CONFIG_DIR_NAME as I,getPromptsDir as C}from"../../config.js";import{parseFrontmatter as N}from"../../utils/frontmatter.js";function _(t){const r=[];let e="",s=null;for(let c=0;c<t.length;c++){const n=t[c];s?n===s?s=null:e+=n:n==='"'||n==="'"?s=n:n===" "||n==="	"?e&&(r.push(e),e=""):e+=n}return e&&r.push(e),r}a(_,"parseCommandArgs");function v(t,r){let e=t;e=e.replace(/\$(\d+)/g,(c,n)=>{const i=parseInt(n,10)-1;return r[i]??""}),e=e.replace(/\$\{@:(\d+)(?::(\d+))?\}/g,(c,n,i)=>{let o=parseInt(n,10)-1;if(o<0&&(o=0),i){const l=parseInt(i,10);return r.slice(o,o+l).join(" ")}return r.slice(o).join(" ")});const s=r.join(" ");return e=e.replace(/\$ARGUMENTS/g,s),e=e.replace(/\$@/g,s),e}a(v,"substituteArgs");function S(t,r,e){try{const s=T(t,"utf-8"),{frontmatter:c,body:n}=N(s),i=j(t).replace(/\.md$/,"");let o=c.description||"";if(!o){const l=n.split(`
+`).find(g=>g.trim());l&&(o=l.slice(0,60),l.length>60&&(o+="..."))}return o=o?`${o} ${e}`:e,{name:i,description:o,content:n,source:r,filePath:t}}catch{return null}}a(S,"loadTemplateFromFile");function b(t,r,e){const s=[];if(!F(t))return s;try{const c=w(t,{withFileTypes:!0});for(const n of c){const i=f(t,n.name);let o=n.isFile();if(n.isSymbolicLink())try{o=$(i).isFile()}catch{continue}if(o&&n.name.endsWith(".md")){const l=S(i,r,e);l&&s.push(l)}}}catch{return s}return s}a(b,"loadTemplatesFromDir");function z(t){const r=t.trim();return r==="~"?D():r.startsWith("~/")?f(D(),r.slice(2)):r.startsWith("~")?f(D(),r.slice(1)):r}a(z,"normalizePath");function R(t,r){const e=z(t);return x(e)?e:h(r,e)}a(R,"resolvePromptPath");function E(t){return`(path:${j(t).replace(/\.md$/,"")||"path"})`}a(E,"buildPathSourceLabel");function Q(t={}){const r=t.cwd??process.cwd(),e=t.agentDir??C(),s=t.promptPaths??[],c=t.includeDefaults??!0,n=[];if(c){const u=t.agentDir?f(t.agentDir,"prompts"):e;n.push(...b(u,"user","(user)"));const p=h(r,I,"prompts");n.push(...b(p,"project","(project)"))}const i=t.agentDir?f(t.agentDir,"prompts"):e,o=h(r,I,"prompts"),l=a((u,p)=>{const m=h(p);if(u===m)return!0;const d=m.endsWith(A)?m:`${m}${A}`;return u.startsWith(d)},"isUnderPath"),g=a(u=>{if(!c){if(l(u,i))return{source:"user",label:"(user)"};if(l(u,o))return{source:"project",label:"(project)"}}return{source:"path",label:E(u)}},"getSourceInfo");for(const u of s){const p=R(u,r);if(F(p))try{const m=$(p),{source:d,label:y}=g(p);if(m.isDirectory())n.push(...b(p,d,y));else if(m.isFile()&&p.endsWith(".md")){const P=S(p,d,y);P&&n.push(P)}}catch{}}return n}a(Q,"loadPromptTemplates");function q(t,r){if(!t.startsWith("/"))return t;const e=t.indexOf(" "),s=e===-1?t.slice(1):t.slice(1,e),c=e===-1?"":t.slice(e+1),n=r.find(i=>i.name===s);if(n){const i=_(c);return v(n.content,i)}return t}a(q,"expandPromptTemplate");export{q as expandPromptTemplate,Q as loadPromptTemplates,_ as parseCommandArgs,v as substituteArgs};

package/dist/core/prompt/system-prompt.d.ts

@@ -0,0 +1,24 @@
+import { type Skill } from "../skills.js";
+export interface BuildSystemPromptOptions {
+    /** Custom system prompt (replaces default). */
+    customPrompt?: string;
+    /** Tools to include in prompt. Default: [read, bash, edit, write] */
+    selectedTools?: string[];
+    /** Text to append to system prompt. */
+    appendSystemPrompt?: string;
+    /** Working directory. Default: process.cwd() */
+    cwd?: string;
+    /** Preloaded context files. */
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Preloaded skills. */
+    skills?: Skill[];
+    /** Soul injection text (AI personality) */
+    soulInjection?: string;
+    /** Guidance for extension tools (collected from ToolDefinition.guidance) */
+    extensionToolsGuidance?: Record<string, string>;
+}
+/** Build system prompt from tools, rules, and context */
+export declare function buildSystemPrompt(options?: BuildSystemPromptOptions): string;

package/dist/core/prompt/system-prompt.js

@@ -0,0 +1,139 @@
+var G=Object.defineProperty;var h=(n,i)=>G(n,"name",{value:i,configurable:!0});import{getDocsPath as q,getExamplesPath as B,getReadmePath as K}from"../../config.js";import{formatSkillsForPrompt as S}from"../skills.js";import{toolGuidance as N}from"../tools/index.js";const p=N;function z(n){return n?.trim()?["## Stable Personality Layer","Use this section for long-term collaboration style, personality, and relationship cues only.","Do not repeat short-term presence lines, temporary memory recall blocks, or raw factual preference lists unless the user asks.","",n.trim()].join(`
+`):""}h(z,"buildSoulSection");function X(n={}){const{customPrompt:i,selectedTools:r,appendSystemPrompt:f,cwd:O,contextFiles:T,skills:I,soulInjection:E,extensionToolsGuidance:u={}}=n,g=O??process.cwd(),y=new Date().toLocaleString("en-US",{weekday:"long",year:"numeric",month:"long",day:"numeric",hour:"2-digit",minute:"2-digit",second:"2-digit",timeZoneName:"short"}),P="\nFor exact current time or any date-sensitive reasoning, you must use the `time` tool before answering. This includes questions about the current time, current date, today, tomorrow, yesterday, this week, deadlines, elapsed time, or anything that depends on the real system clock. Do not rely only on this prompt timestamp for those answers.",a=f?`
+
+${f}`:"",c=z(E),l=T??[],d=I??[];if(i){let e=i;if(c&&(e+=`
+
+${c}`),a&&(e+=a),l.length>0){e+=`
+
+# Project Context
+
+`,e+=`Project-related rules and specifications:
+
+`;for(const{path:A,content:U}of l)e+=`## ${A}
+
+${U}
+
+`}return(!r||r.includes("read"))&&d.length>0&&(e+=S(d)),e+=`
+Current date and time: ${y}`,e+=`
+Current working directory: ${g}`,e+=P,e}const F=K(),H=q(),W=B(),s=(r||["read","bash","edit","write","time"]).filter(e=>e in p),C={...p,...u},M=s.length>0?s.map(e=>`- ${e}: ${C[e]}`).join(`
+`):"(none)",w=r?.filter(e=>!p[e]&&u[e])||[],b=w.length>0?w.map(e=>`- ${e}: ${u[e]}`).join(`
+`):null,o=[],k=s.includes("bash"),m=s.includes("edit"),x=s.includes("write"),v=s.includes("grep"),$=s.includes("find"),D=s.includes("ls"),R=s.includes("read");k&&!v&&!$&&!D?o.push("Use bash for ls, rg, find and other file operations"):k&&(v||$||D)&&o.push("Prefer using grep/find/ls tools for file exploration (faster, respects .gitignore)"),R&&m&&o.push("Before editing, use read to view file content. Must use this tool, not cat or sed."),m&&o.push("Use edit for precise modifications (old text must match exactly)"),x&&o.push("Use write only when creating new files or complete rewrite"),(m||x)&&o.push("When summarizing your actions, output plain text directly, don't use cat or bash to show what you did"),o.push("Be concise when performing technical tasks (code, file ops, analysis). For casual conversation, respond naturally and warmly."),o.push("Clearly label file paths when operating on files");const L=o.map(e=>`- ${e}`).join(`
+`);let t="";if(t+=`You are the writing assistant in catui. You help users by reading files, running commands, editing and writing text.
+
+Available tools:
+${M}${b?`
+${b}`:""}
+
+Besides the above tools, you may also have access to other custom tools based on project configuration.
+
+Rules:
+${L}
+
+## P3 Header and Progressive Disclosure
+
+Each code file has a P3 format DIP header for quick relevance assessment:
+
+[P3 Header Format Example]
+/**
+ * [WHO]: Provides {exported functions/components/types/constants}
+ * [FROM]: Depends on {module/package/file} for {specific capability}
+ * [TO]: Consumed by {adjacent modules or downstream consumers}
+ * [HERE]: {file path} within {module}; relationship with neighbors}
+ */
+
+**Four Questions Meaning**:
+- **WHO**: What does this file provide (exports, public API)
+- **FROM**: What does this file depend on (upstream dependencies)
+- **TO**: Who uses this file (downstream consumers)
+- **HERE**: Where is this file, and what is its relationship with neighbors
+
+**Header Reading Protocol**:
+
+1. **Read header first**: When encountering a code file, read the P3 header first (usually first 5-8 lines)
+2. **Assess relevance**:
+   - If current task involves WHO (what provides), FROM (what depends), TO (who uses), HERE (where) declared in header \u2192 Continue reading
+   - If not relevant \u2192 **Stop reading immediately**, save context
+3. **Judgment criteria**:
+   - Does your task need this file's WHO?
+   - Is your task within this file's HERE scope?
+   - Does your task depend on this file's FROM?
+
+**Progressive Disclosure Context Savings**:
+- Large projects may have hundreds of files
+- Header is only 4 lines, while file may be hundreds of lines
+- Read header = O(1), read full = O(n)
+- Learning "header doesn't match then skip" is key to efficiency
+
+**DIP Header Requirements When Generating Files**:
+- Any created code file must include complete P3 header
+- WHO must accurately describe exported public API (specific function/type names)
+- FROM must list key dependencies
+- TO must explain downstream consumers
+- HERE must clarify module coordinates and upstream/downstream relationships
+
+## catui.md Project Initialization Protocol
+
+When first operating files in a project, check if \`catui.md\` (or \`AGENT.md\`, legacy \`CLAUDE.md\`) exists in root:
+
+**If not exists**:
+1. Suggest user create \`catui.md\`
+2. Generate template content including:
+   - Project overview (name, tech stack, core features)
+   - Directory structure (P2 module list placeholder)
+   - DIP protocol explanation (P3 header spec, progressive disclosure mindset)
+   - Rules (code style, commit conventions, etc.)
+3. Write file after user confirmation
+
+**catui.md Template Structure**:
+
+[catui.md Template Content]
+# \${Project Name}
+
+> P1 | Project root document and navigation map
+
+## Project Overview
+\${One sentence describing what the project is}
+
+**Tech Stack**: \${List main technologies}
+**Core Features**: \${2-3 sentences describing core capabilities}
+
+## Directory Structure
+\${P2 module list placeholder, to be filled by AI}
+
+## DIP Protocol
+
+This project uses **Dual-phase Isomorphic Documentation**:
+
+- P1: Root document (this document), global topology
+- P2: Module-level documents, member lists
+- P3: File header comments, quick relevance judgment
+
+See: https://catui.github.io/dip
+
+## Rules
+\${P0 code rules placeholder}
+
+---
+*This file is auto-generated by Catui, can be modified per project needs*
+
+Only read the following docs when user asks about catui-agent, SDK, extensions, themes, skills or TUI:
+- Main doc: ${F}
+- More docs: ${H}
+- Examples: ${W} (extensions, custom tools, SDK)
+- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integration (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), packages (docs/packages.md)
+- When handling related topics, first read docs and examples, then implement following cross-references in .md files
+- Must fully read .md files and follow related links (e.g., TUI API details in tui.md)`,c&&(t+=`
+
+${c}`),a&&(t+=a),l.length>0){t+=`
+
+# Project Context
+
+`,t+=`Project-related rules and specifications:
+
+`;for(const{path:e,content:j}of l)t+=`## ${e}
+
+${j}
+
+`}return R&&d.length>0&&(t+=S(d)),t+=`
+Current date and time: ${y}`,t+=`
+Current working directory: ${g}`,t+=P,t}h(X,"buildSystemPrompt");export{X as buildSystemPrompt};