kandown 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.24.0 — 2026-07-20 — "Work Output Configurator"
+
+- **Added**: **`kandown work` Output Configurator** — added a new Settings panel under Agent configuration that lets each project control the markdown emitted by `kandown work`. Users can enable or disable the base rules, project instructions, and live board digest blocks without editing generated files by hand.
+- **Added**: **Raw Template Mode for Agent Context** — added an advanced raw editor for the complete `kandown work` output with `{{baseRules}}`, `{{projectInstructions}}`, and `{{boardDigest}}` variables. This gives power users full control over the final prompt while keeping the source of truth in `.kandown/kandown.json`.
+- **Added**: **Token-Efficient Concise Rules Mode** — added a compact Kandown rules preset for `kandown work` that keeps the essential task-management contract while dramatically reducing prompt size for cost-sensitive or context-limited agents.
+- **Added**: **Estimated Token Counter and Output Preview** — the Settings configurator now previews the generated `kandown work` markdown and displays an approximate token estimate so users can tune the output before handing it to an agent.
+- **Added**: **Project Instructions Editor** — added authenticated web/server helpers and UI editing for `.kandown/instructions.md`, keeping custom project behavior inside `.kandown/` instead of polluting project-root agent files.
+- **Changed**: **Project-Scoped Work Output Storage** — added `agent.workOutput` to `.kandown/kandown.json` and the default template config, including section toggles, section ordering, digest detail toggles, base-rule verbosity, and raw template content.
+- **Changed**: **Configurable Board Digest Detail** — the generated board digest can now hide column counts, task lists, priorities, assignees, blocked-by annotations, and next-actionable-task output independently to minimize tokens when desired.
+- **Fixed**: **Safe `.kandown/AGENT_KANDOWN.md` Healing** — Kandown now recreates `.kandown/AGENT_KANDOWN.md` when missing and overwrites malformed or stale generated copies from the package template, while keeping all generated reference docs inside `.kandown/` only.
+
 ## 0.23.0 — 2026-07-20 — "Theme Switcher & Auto Update"
 
 - **Added**: **Animated Theme Switcher** — added a shadcn-style three-option theme switcher under `src/components/ui/theme-switcher-1.tsx` with system, light, and dark choices, lucide icons, and Motion layout animation.

package/README.md

@@ -131,11 +131,14 @@ kandown commit -m "tasks: add auth refactor"
 Running `kandown work` prints, as plain markdown on stdout:
 
 1. **The agent rules** — always fresh, served straight from the installed CLI version instead of a copy that goes stale the moment the package updates.
-2. **Global instructions** (optional) — `~/.kandown/instructions.md`, applied to every kandown project on this machine (personal conventions, team-wide rules).
-3. **Project instructions** (optional) — `.kandown/instructions.md`, this project only (stack quirks, "always use pnpm", commit message language, etc).
-4. **A live board digest** — column counts, tasks per column with blocked-by annotations, and a computed **"next actionable task"** (closest to done, unblocked, highest priority) — so the agent gets its context in the same call.
+2. **Project instructions** (optional) — `.kandown/instructions.md`, this project only (stack quirks, "always use pnpm", commit message language, token-efficient agent preferences, etc).
+3. **A live board digest** — column counts, tasks per column with blocked-by annotations, and a computed **"next actionable task"** (closest to done, unblocked, highest priority) — so the agent gets its context in the same call.
 
-This removes the drift problem of a rules block frozen into every project's `AGENTS.md` at init time, keeps the injected footprint to one line, and lets you layer instructions globally or per project without touching the agent file at all.
+The Settings page includes an **Agent → kandown work output** configurator. You can toggle each generated block, switch the base rules to a concise token-efficient mode, hide detailed digest fields, see an estimated token count, or use **Raw template** mode to control the complete output with `{{baseRules}}`, `{{projectInstructions}}`, and `{{boardDigest}}` variables.
+
+Kandown keeps generated agent reference docs inside `.kandown/` only. If `.kandown/AGENT_KANDOWN.md` is missing, malformed, or an outdated generated copy, the CLI recreates it from the installed package template. Custom behavior belongs in `.kandown/instructions.md` and `.kandown/kandown.json`, not in project-root agent files.
+
+This removes the drift problem of a rules block frozen into every project's `AGENTS.md` at init time, keeps the injected footprint to one line, and lets you layer project instructions without touching the agent file at all.
 
 > **Upgrading from before v0.18.0?** `kandown shell <cmd>` was removed (no alias) — the commands are now top-level: `kandown list/show/create/move/assign/commit`. Existing projects keep their old `AGENTS.md`/`CLAUDE.md` block until you re-run `kandown init`. The CLI prints a one-time notice about this the next time you run an interactive command after updating — see [Environment variables](#environment-variables) if you want to silence version-check output entirely.
 

package/bin/kandown.js

@@ -869,6 +869,7 @@ function ensureKandownDir(rawArgs) {
     } else if (migration.skipped) {
       info('Both .kandown/tasks/ and ./tasks/ have files — leaving both in place');
     }
+    syncKandownAgentDoc(kandownDir);
     return { kandownDir, alreadyExisted: true };
   }
 
@@ -894,13 +895,13 @@ function doInit(args, cwd, kandownPath, kandownDir) {
   copyFileSync(htmlSrc, htmlDest);
   success('kandown.html');
 
-  // 📖 AGENT.md and AGENT_KANDOWN.md are intentionally NOT copied into new
-  // projects anymore. Both `kandown work` and the TUI's agent launcher (`a`)
-  // now read the rules straight from this package's templates/AGENT_KANDOWN.md
-  // at call time — a per-project copy would only go stale the moment the
-  // package updates, with nothing to keep it in sync. Existing projects with
-  // an old copy are left alone (never auto-deleted); customization now goes
-  // in `.kandown/instructions.md` / `~/.kandown/instructions.md` instead.
+  // 📖 Keep the generated agent reference inside `.kandown/` only. It is safe
+  // to recreate/overwrite because user-specific behavior belongs in
+  // `.kandown/instructions.md` or the `agent.workOutput` config, not in this
+  // generated package reference.
+  syncKandownAgentDoc(kandownDir);
+  success('AGENT_KANDOWN.md');
+
   const templatesDir = join(PKG_ROOT, 'templates');
   if (!existsSync(join(kandownDir, 'README.md'))) {
     copyFileSync(join(templatesDir, 'README.md'), join(kandownDir, 'README.md'));
@@ -1557,6 +1558,93 @@ function priorityRank(p) {
   return Object.prototype.hasOwnProperty.call(PRIORITY_RANK, p) ? PRIORITY_RANK[p] : 4;
 }
 
+const WORK_OUTPUT_SECTION_IDS = ['baseRules', 'projectInstructions', 'boardDigest'];
+const CONCISE_AGENT_RULES = `# Kandown agent rules — concise
+
+- Task state lives in project-root \`tasks/*.md\`; do not maintain a separate board index.
+- Before work, read the relevant task file and keep it updated while you progress.
+- Move tasks by editing frontmatter \`status:\`; complete work by setting \`status: Done\` and adding a markdown \`report:\` summary.
+- Update subtasks in-place: \`- [ ]\` → \`- [x]\`, with a short \`report:\` line for meaningful progress.
+- Board columns live in \`.kandown/kandown.json\` under \`board.columns\`; project instructions live in \`.kandown/instructions.md\`.
+- Never put Kandown task data inside \`.kandown/\`; tasks belong in \`./tasks/\`.`;
+const DEFAULT_WORK_OUTPUT = {
+  mode: 'blocks',
+  includeBaseRules: true,
+  baseRulesMode: 'full',
+  includeProjectInstructions: true,
+  includeBoardDigest: true,
+  sectionOrder: WORK_OUTPUT_SECTION_IDS,
+  rawTemplate: '{{baseRules}}\n\n---\n\n{{projectInstructions}}\n\n---\n\n{{boardDigest}}',
+  boardDigest: {
+    showColumnCounts: true,
+    showTasks: true,
+    showPriority: true,
+    showAssignee: true,
+    showBlockedBy: true,
+    showNextActionable: true,
+  },
+};
+
+function safePlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function normalizeWorkOutputConfig(config) {
+  const raw = safePlainObject(safePlainObject(config?.agent).workOutput);
+  const digest = safePlainObject(raw.boardDigest);
+  const sectionOrder = Array.isArray(raw.sectionOrder)
+    ? raw.sectionOrder.filter(id => WORK_OUTPUT_SECTION_IDS.includes(id))
+    : DEFAULT_WORK_OUTPUT.sectionOrder;
+  const order = sectionOrder.length > 0 ? sectionOrder : DEFAULT_WORK_OUTPUT.sectionOrder;
+  return {
+    ...DEFAULT_WORK_OUTPUT,
+    ...raw,
+    mode: raw.mode === 'raw' ? 'raw' : 'blocks',
+    baseRulesMode: raw.baseRulesMode === 'concise' ? 'concise' : 'full',
+    sectionOrder: order,
+    rawTemplate: typeof raw.rawTemplate === 'string' && raw.rawTemplate.trim()
+      ? raw.rawTemplate
+      : DEFAULT_WORK_OUTPUT.rawTemplate,
+    boardDigest: { ...DEFAULT_WORK_OUTPUT.boardDigest, ...digest },
+  };
+}
+
+function readBaseAgentRules(mode = 'full') {
+  if (mode === 'concise') return CONCISE_AGENT_RULES;
+  try {
+    return readFileSync(join(PKG_ROOT, 'templates', 'AGENT_KANDOWN.md'), 'utf8').trim();
+  } catch (e) {
+    warn(`Could not read base rules (${e.message})`);
+    return '';
+  }
+}
+
+function syncKandownAgentDoc(kandownDir) {
+  const source = join(PKG_ROOT, 'templates', 'AGENT_KANDOWN.md');
+  const target = join(kandownDir, 'AGENT_KANDOWN.md');
+  if (!existsSync(source)) return false;
+  const expected = readFileSync(source, 'utf8');
+  const existing = existsSync(target) ? readFileSync(target, 'utf8') : null;
+  const isMissing = existing === null;
+  const isMalformed = existing !== null && !existing.includes('# Kandown') && !existing.includes('## The System');
+  const isStaleGeneratedDoc = existing !== null && existing.includes('# Kandown') && existing !== expected;
+
+  if (isMissing || isMalformed || isStaleGeneratedDoc) {
+    atomicWriteFileSync(target, expected.endsWith('\n') ? expected : `${expected}\n`);
+    return true;
+  }
+  return false;
+}
+
+function applyWorkRawTemplate(template, blocks) {
+  return template
+    .replaceAll('{{baseRules}}', blocks.baseRules)
+    .replaceAll('{{projectInstructions}}', blocks.projectInstructions)
+    .replaceAll('{{boardDigest}}', blocks.boardDigest)
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
 /**
  * 📖 Builds the "Current board" section: column counts, tasks per column
  * (with blocked-by annotations), and a "Next actionable task" pick — the
@@ -1565,7 +1653,8 @@ function priorityRank(p) {
  * `depends_on`, tie-broken by priority. Mirrors the same gate logic used by
  * `move`/the TUI/the web store.
  */
-function buildBoardDigest(kandownDir) {
+function buildBoardDigest(kandownDir, options = DEFAULT_WORK_OUTPUT.boardDigest) {
+  const digestOptions = { ...DEFAULT_WORK_OUTPUT.boardDigest, ...safePlainObject(options) };
   const config = readKandownConfig(kandownDir);
   const columns = (config && config.board && Array.isArray(config.board.columns) && config.board.columns.length > 0)
     ? config.board.columns
@@ -1608,17 +1697,21 @@ function buildBoardDigest(kandownDir) {
   }
 
   const lines = ['## Current board', ''];
-  lines.push(`**Columns:** ${columns.map(col => `${col} (${(byColumn.get(col) || []).length})`).join(' · ')}`);
-
-  for (const col of columns) {
-    const tasks = (byColumn.get(col) || []).sort((a, b) => priorityRank(a.fm.priority) - priorityRank(b.fm.priority));
-    if (tasks.length === 0) continue;
-    lines.push('', `### ${col}`);
-    for (const t of tasks) {
-      const pri = t.fm.priority ? `[${t.fm.priority}] ` : '';
-      const assignee = t.fm.assignee ? ` (@${t.fm.assignee})` : '';
-      const blockedStr = t.blocked.length > 0 ? ` ⛔ blocked by ${t.blocked.join(', ')}` : '';
-      lines.push(`- ${t.id} ${pri}${t.fm.title || '(untitled)'}${assignee}${blockedStr}`);
+  if (digestOptions.showColumnCounts) {
+    lines.push(`**Columns:** ${columns.map(col => `${col} (${(byColumn.get(col) || []).length})`).join(' · ')}`);
+  }
+
+  if (digestOptions.showTasks) {
+    for (const col of columns) {
+      const tasks = (byColumn.get(col) || []).sort((a, b) => priorityRank(a.fm.priority) - priorityRank(b.fm.priority));
+      if (tasks.length === 0) continue;
+      lines.push('', `### ${col}`);
+      for (const t of tasks) {
+        const pri = digestOptions.showPriority && t.fm.priority ? `[${t.fm.priority}] ` : '';
+        const assignee = digestOptions.showAssignee && t.fm.assignee ? ` (@${t.fm.assignee})` : '';
+        const blockedStr = digestOptions.showBlockedBy && t.blocked.length > 0 ? ` ⛔ blocked by ${t.blocked.join(', ')}` : '';
+        lines.push(`- ${t.id} ${pri}${t.fm.title || '(untitled)'}${assignee}${blockedStr}`);
+      }
     }
   }
 
@@ -1635,30 +1728,23 @@ function buildBoardDigest(kandownDir) {
     return priorityRank(a.fm.priority) - priorityRank(b.fm.priority);
   })[0];
 
-  lines.push('', '### Next actionable task');
-  lines.push(next
-    ? `→ **${next.id}** — ${next.fm.title || '(untitled)'} (${next.fm.priority || 'no priority'}, ${next.fm.status || columns[0]})`
-    : 'None — every task is done, archived, or blocked.');
+  if (digestOptions.showNextActionable) {
+    lines.push('', '### Next actionable task');
+    lines.push(next
+      ? `→ **${next.id}** — ${next.fm.title || '(untitled)'} (${next.fm.priority || 'no priority'}, ${next.fm.status || columns[0]})`
+      : 'None — every task is done, archived, or blocked.');
+  }
 
   return lines.join('\n');
 }
 
 async function cmdWork(rawArgs) {
   const { kandownDir } = ensureKandownDir(rawArgs);
+  const config = readKandownConfig(kandownDir);
+  const workOutput = normalizeWorkOutputConfig(config);
+  syncKandownAgentDoc(kandownDir);
 
-  let baseRules = '';
-  try {
-    baseRules = readFileSync(join(PKG_ROOT, 'templates', 'AGENT_KANDOWN.md'), 'utf8').trim();
-  } catch (e) {
-    warn(`Could not read base rules (${e.message})`);
-  }
-
-  let globalInstructions = '';
-  const globalPath = join(homedir(), '.kandown', 'instructions.md');
-  if (existsSync(globalPath)) {
-    try { globalInstructions = readFileSync(globalPath, 'utf8').trim(); }
-    catch (e) { warn(`Could not read global instructions (${e.message})`); }
-  }
+  const baseRules = readBaseAgentRules(workOutput.baseRulesMode);
 
   let projectInstructions = '';
   const projectPath = join(kandownDir, 'instructions.md');
@@ -1667,10 +1753,23 @@ async function cmdWork(rawArgs) {
     catch (e) { warn(`Could not read project instructions (${e.message})`); }
   }
 
-  const sections = [baseRules];
-  if (globalInstructions) sections.push(`## Global instructions\n\n${globalInstructions}`);
-  if (projectInstructions) sections.push(`## Project-specific instructions\n\n${projectInstructions}`);
-  sections.push(buildBoardDigest(kandownDir));
+  const blocks = {
+    baseRules,
+    projectInstructions: projectInstructions ? `## Project-specific instructions\n\n${projectInstructions}` : '',
+    boardDigest: buildBoardDigest(kandownDir, workOutput.boardDigest),
+  };
+
+  if (workOutput.mode === 'raw') {
+    out(applyWorkRawTemplate(workOutput.rawTemplate, blocks));
+    return;
+  }
+
+  const sections = [];
+  for (const sectionId of workOutput.sectionOrder) {
+    if (sectionId === 'baseRules' && workOutput.includeBaseRules) sections.push(blocks.baseRules);
+    if (sectionId === 'projectInstructions' && workOutput.includeProjectInstructions) sections.push(blocks.projectInstructions);
+    if (sectionId === 'boardDigest' && workOutput.includeBoardDigest) sections.push(blocks.boardDigest);
+  }
 
   out(sections.filter(Boolean).join('\n\n---\n\n'));
 }
@@ -2232,6 +2331,30 @@ function putConfig(req, res, kandownDir) {
   });
 }
 
+function getInstructions(res, kandownDir) {
+  const instructionsPath = join(kandownDir, 'instructions.md');
+  if (!existsSync(instructionsPath)) {
+    writeText(res, 200, '');
+    return;
+  }
+  try {
+    writeText(res, 200, readFileSync(instructionsPath, 'utf8'));
+  } catch (e) {
+    writeText(res, 500, `Failed to read instructions: ${e.message}`);
+  }
+}
+
+function putInstructions(req, res, kandownDir) {
+  readBody(req).then(body => {
+    const instructionsPath = join(kandownDir, 'instructions.md');
+    const normalized = body.trim() ? body.replace(/\s+$/, '') + '\n' : '';
+    atomicWriteFileSync(instructionsPath, normalized);
+    writeJson(res, 200, { ok: true });
+  }).catch(e => {
+    writeJson(res, e.statusCode || 500, { error: `Failed to write instructions: ${e.message}` });
+  });
+}
+
 function getBoard(res, kandownDir) {
   const boardPath = join(kandownDir, 'board.md');
   if (!existsSync(boardPath)) {
@@ -2505,6 +2628,11 @@ function handleApi(req, res, url, kandownDir) {
     if (req.method === 'PUT') return putConfig(req, res, kandownDir);
   }
 
+  if (resource === 'instructions') {
+    if (req.method === 'GET') return getInstructions(res, kandownDir);
+    if (req.method === 'PUT') return putInstructions(req, res, kandownDir);
+  }
+
   if (resource === 'board') {
     if (req.method === 'GET') return getBoard(res, kandownDir);
     if (req.method === 'PUT') return putBoard(req, res, kandownDir);