project-logbook 0.3.1 → 0.3.3

package/README.md

@@ -17,18 +17,21 @@ Each entry in `logbook/` consists of:
 
 ## Installation
 ```bash
-npm i project-loogbook -g
+npm i project-logbook -g
 ```
 
 ## Commands
-- `logbook init`: Initialize configuration and directory.
-- `logbook new <id> <slug>`: Create a new entry folder with templates.
-- `logbook start <id>`: Mark a logbook entry as active (writes `.logbook-active` lockfile). The active entry is also auto-detected from the current Git branch — a branch named `feat/LB-123-my-feature` will automatically resolve to entry `LB-123`.
-- `logbook release`: Release the active logbook entry (removes `.logbook-active` lockfile).
-- `logbook log <message>`: Append a timestamped log entry to the active `log.md`.
-- `logbook list`: List all logbook entries with their status.
-- `logbook lint`: Validate structure, frontmatter, and internal links.
-- `logbook build`: Compile logbook entries into a static HTML site (default: `public/`).
-- `logbook preview`: Build and open the logbook in your default browser.
-- `logbook upgrade`: Synchronize core project files (like `CONTRIBUTING.md`) with latest templates.
-- `logbook steer`: Output agentic protocol for AI assistants.
+
+| Command | Description |
+|---|---|
+| `logbook init` | Initialize configuration and directory. |
+| `logbook new <id> <slug>` | Create a new entry folder with templates. |
+| `logbook start <id>` | Mark a logbook entry as active (writes `.logbook-active` lockfile). The active entry is also auto-detected from the current Git branch — a branch named `feat/LB-123-my-feature` will automatically resolve to entry `LB-123`. |
+| `logbook release` | Release the active logbook entry (removes `.logbook-active` lockfile). |
+| `logbook log <message>` | Append a timestamped log entry to the active `log.md`. |
+| `logbook list` | List all logbook entries with their status. |
+| `logbook lint` | Validate structure, frontmatter, and internal links. |
+| `logbook build` | Compile logbook entries into a static HTML site (default: `public/`). |
+| `logbook preview` | Build and open the logbook in your default browser. |
+| `logbook upgrade` | Synchronize core project files (like `CONTRIBUTING.md`) with latest templates. |
+| `logbook steer` | Output agentic protocol for AI assistants. |

package/dist/commands/build.js

@@ -5,14 +5,25 @@ import { getConfig, getWorkspaces } from '../lib/config.js';
 import { layout, timelineTemplate } from '../lib/templates.js';
 import { getStyles } from '../lib/styles.js';
 import { getClientScript } from '../lib/logbook-client.js';
-import { mdToHtml, buildProjectMdFiles, renderPost } from '../lib/build-helpers.js';
+import { mdToHtml, buildProjectMdFiles, renderPost, generateBuildMeta } from '../lib/build-helpers.js';
 import { mdToHtmlWithImages, copyImages } from '../lib/image-helpers.js';
 import { getGitCommits, getGitTags } from '../lib/git-helpers.js';
 import { formatRelativeDate, getMonthYear, getSortTime } from '../utils/date.js';
 import { getLogbookEntries } from '../utils/fs.js';
 import { getAboutContent } from '../lib/about-content.js';
+import { groupTimelineItems } from '../utils/timeline-helpers.js';
 const pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 const version = pkg.version;
+/** Normalises a frontmatter field that may be a scalar string or a YAML list of strings. */
+const toDisplayString = (v) => {
+    if (typeof v === 'string')
+        return v || undefined;
+    if (Array.isArray(v)) {
+        const joined = v.filter((x) => typeof x === 'string').join(' + ');
+        return joined || undefined;
+    }
+    return undefined;
+};
 export async function build() {
     const config = getConfig();
     const logbookDir = join(process.cwd(), config.logbookDir);
@@ -102,9 +113,9 @@ export async function build() {
             tags: Array.isArray(data.tags) ? data.tags.filter((t) => typeof t === 'string') : [],
             workspaces: entryWorkspaces,
             title: typeof data.title === 'string' ? data.title : undefined,
-            harness: typeof data.harness === 'string' ? data.harness : undefined,
-            llm: typeof data.llm === 'string' ? data.llm : undefined,
-            prompter: typeof data.prompter === 'string' ? data.prompter : undefined,
+            harness: toDisplayString(data.harness),
+            llm: toDisplayString(data.llm),
+            prompter: toDisplayString(data.prompter),
         });
     }
     // Fetch global git commits and tags concurrently.
@@ -134,18 +145,49 @@ export async function build() {
         return bEnd - aEnd;
     });
     await Promise.all(timelineEntries.map((entry, i) => renderPost(entry, i, timelineEntries, { logbookDir, outputDir, config, version, buildTime })));
-    const groups = groupTimelineItems(timelineEntries, commitItems, tagItems);
-    const timelineContent = timelineTemplate({ projectName: config.projectName, version, buildTime, groups, readmeHtml, aboutHtml, jiraBaseUrl: config.jiraBaseUrl, jiraPrefix: config.jiraPrefix }); // prettier-ignore
-    const buildMeta = `Generated by ${config.projectName} v${version} • ${buildTime}`;
-    const timelineHtml = layout({
-        title: 'Timeline',
-        projectName: config.projectName,
-        basePath: './',
-        buildMeta,
-        header: timelineContent.split('</header>')[0] + '</header>',
-        content: timelineContent.split('</header>')[1],
-    });
-    await fs.writeFile(join(outputDir, 'index.html'), timelineHtml);
+    // Build the full merged, chronologically sorted groups once, then paginate the flat item list.
+    const allGroups = groupTimelineItems(timelineEntries, commitItems, tagItems);
+    const flatItems = allGroups.flatMap((g) => g.items);
+    const pageSize = 50;
+    const totalPages = Math.max(1, Math.ceil(flatItems.length / pageSize));
+    for (let i = 0; i < totalPages; i++) {
+        const currentPage = i + 1;
+        const pageItems = flatItems.slice(i * pageSize, (i + 1) * pageSize);
+        // Re-group this page's items by month for rendering.
+        const pageGroups = [];
+        for (const item of pageItems) {
+            const month = item.monthGroup;
+            let group = pageGroups.find((g) => g.month === month);
+            if (!group) {
+                group = { month, items: [] };
+                pageGroups.push(group);
+            }
+            group.items.push(item);
+        }
+        const timelineContent = timelineTemplate({
+            projectName: config.projectName,
+            version,
+            buildTime,
+            groups: pageGroups,
+            readmeHtml,
+            aboutHtml,
+            jiraBaseUrl: config.jiraBaseUrl,
+            jiraPrefix: config.jiraPrefix,
+            currentPage,
+            totalPages,
+        }); // prettier-ignore
+        const buildMeta = generateBuildMeta(version, buildTime);
+        const timelineHtml = layout({
+            title: 'Timeline',
+            projectName: config.projectName,
+            basePath: './',
+            buildMeta,
+            header: timelineContent.split('</header>')[0] + '</header>',
+            content: timelineContent.split('</header>')[1],
+        });
+        const fileName = currentPage === 1 ? 'index.html' : `index-${currentPage}.html`;
+        await fs.writeFile(join(outputDir, fileName), timelineHtml);
+    }
     await buildProjectMdFiles(process.cwd(), outputDir, [config.logbookDir, config.outputDir, 'node_modules'], {
         config,
         version,
@@ -153,22 +195,3 @@ export async function build() {
     });
     console.log(chalk.green(`\nSuccessfully built logbook to ${config.outputDir}/`));
 }
-function groupTimelineItems(entries, commits, tags) {
-    const toMs = (item) => {
-        if (item.kind === 'entry')
-            return item.dateEnd ? new Date(item.dateEnd).getTime() : new Date(item.dateStart).getTime();
-        return new Date(item.timestamp).getTime();
-    };
-    const all = [...entries, ...commits, ...tags];
-    all.sort((a, b) => toMs(b) - toMs(a));
-    const groups = [];
-    for (const item of all) {
-        let group = groups.find((g) => g.month === item.monthGroup);
-        if (!group) {
-            group = { month: item.monthGroup, items: [] };
-            groups.push(group);
-        }
-        group.items.push(item);
-    }
-    return groups;
-}

package/dist/commands/lint.js

@@ -20,7 +20,7 @@ export async function lint() {
     // 2. Entry-level checks
     const logbookEntries = await getLogbookEntries(logbookDir);
     let passedCount = 0;
-    let skippedCount = 0;
+    let skippedCount = 0; // Re-introducing skippedCount
     for (const entry of logbookEntries) {
         if (!entry.hasIndex) {
             console.error(chalk.red(`  [MISSING] ${entry.slug}/index.md`));
@@ -62,17 +62,9 @@ export async function lint() {
  * meaning it should be exempt from linting.
  */
 function isDraft(entry) {
-    const dataValues = Object.values(entry.data)
-        .filter((v) => typeof v === 'string')
-        .join('\n');
-    const frontmatterHasPlaceholders = dataValues.includes('[DATE_END]') ||
-        dataValues.includes('[DATE_START]') ||
-        dataValues.includes('[WRITE_SUMMARY_HERE]') ||
-        dataValues.includes('[PROMPTER]') ||
-        dataValues.includes('[HARNESS]') ||
-        dataValues.includes('[LLM]');
-    const contentWithoutCode = entry.content.replace(/`[^`]*`/g, '');
-    const bodyHasPlaceholders = contentWithoutCode.includes('TODO:') ||
-        entry.content.includes('Write a polished, highly readable "short story" of the change here.');
-    return frontmatterHasPlaceholders || bodyHasPlaceholders;
+    const frontmatter = entry.data; // Correctly access the data property
+    // An entry is a draft if:
+    // 1. The 'dateStart' key is missing from frontmatter (i.e., undefined or null).
+    // 2. OR the string representation of 'dateStart' is '[DATE_START]'.
+    return !frontmatter?.dateStart || String(frontmatter.dateStart) === 'DATE_START';
 }

package/dist/index.js

@@ -75,12 +75,12 @@ program
     await list(options);
 });
 program
-    .command('log <message...>')
+    .command('log <message>')
     .description('Append a timestamped log entry to the active log.md (e.g. logbook log "Did a thing")')
     .option('-i, --id <id>', 'Override active logbook entry ID')
-    .action(async (messages, options) => {
+    .action(async (message, options) => {
     const { log } = await import('./commands/log.js');
-    await log(messages, options);
+    await log([message], options);
 });
 program
     .command('steer')

package/dist/lib/build-helpers.d.ts

@@ -1,6 +1,8 @@
 import type { LogbookConfig } from './config.js';
 import type { TimelineEntry } from './template-types.js';
 export declare function mdToHtml(md: string): Promise<string>;
+/** Process entry markdown with image path rewriting */
+export declare function mdToHtmlWithImagePathRewrite(md: string): Promise<string>;
 export declare function buildProjectMdFiles(projectRoot: string, outputDir: string, excludeDirs: string[], ctx: {
     config: LogbookConfig;
     version: string;
@@ -13,3 +15,8 @@ export declare function renderPost(data: TimelineEntry, i: number, allEntries: T
     version: string;
     buildTime: string;
 }): Promise<void>;
+/**
+ * Generate the standard footer metadata string.
+ * Always hardcoded to 'Project Logbook CLI' with link to npm.
+ */
+export declare function generateBuildMeta(version: string, buildTime: string): string;

package/dist/lib/build-helpers.js

@@ -2,6 +2,7 @@ import fs from 'fs-extra';
 import { join } from 'node:path';
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
 import remarkRehype from 'remark-rehype';
 import rehypeSlug from 'rehype-slug';
 import rehypeFormat from 'rehype-format';
@@ -9,7 +10,7 @@ import rehypeStringify from 'rehype-stringify';
 import matter from 'gray-matter';
 import { layout, postTemplate } from './templates.js';
 import { getGitCommits } from './git-helpers.js';
-import { mdToHtmlWithImages, extractImagePathsFromMarkdown, copyImages } from './image-helpers.js';
+import { mdToHtmlWithImages, extractImagePathsFromMarkdown, copyImages, rehypeRewriteImagePaths, } from './image-helpers.js';
 /** Rehype plugin: rewrite relative .md links to /index.html equivalents. */
 const rehypeRewriteMdLinks = () => {
     return (tree) => {
@@ -39,15 +40,31 @@ function visitLinks(node, visitor) {
 }
 const processor = unified()
     .use(remarkParse)
+    .use(remarkGfm)
     .use(remarkRehype)
     .use(rehypeSlug)
     .use(rehypeRewriteMdLinks)
     .use(rehypeFormat)
     .use(rehypeStringify);
+/** Processor for entry content with image path rewriting */
+const entryProcessor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype)
+    .use(rehypeSlug)
+    .use(rehypeRewriteMdLinks)
+    .use(rehypeRewriteImagePaths)
+    .use(rehypeFormat)
+    .use(rehypeStringify);
 export async function mdToHtml(md) {
     const result = await processor.process(md);
     return result.toString();
 }
+/** Process entry markdown with image path rewriting */
+export async function mdToHtmlWithImagePathRewrite(md) {
+    const result = await entryProcessor.process(md);
+    return result.toString();
+}
 export async function buildProjectMdFiles(projectRoot, outputDir, excludeDirs, ctx) {
     const entries = await fs.readdir(projectRoot, { withFileTypes: true });
     for (const entry of entries) {
@@ -60,7 +77,7 @@ export async function buildProjectMdFiles(projectRoot, outputDir, excludeDirs, c
         const outDir = join(outputDir, stem);
         const mdContent = await fs.readFile(sourcePath, 'utf8');
         const bodyHtml = await mdToHtml(mdContent);
-        const buildMeta = `Generated by ${ctx.config.projectName} v${ctx.version} • ${ctx.buildTime}`;
+        const buildMeta = generateBuildMeta(ctx.version, ctx.buildTime);
         const pageHtml = layout({
             title: stem,
             projectName: ctx.config.projectName,
@@ -101,7 +118,7 @@ async function renderLinkedMdFiles(markdownSources, entryPath, entryOutputDir, c
             const mdContent = await fs.readFile(sourcePath, 'utf8');
             const bodyHtml = await mdToHtml(mdContent);
             const title = href.replace(/\.md$/i, '');
-            const buildMeta = `Generated by ${ctx.config.projectName} v${ctx.version} • ${ctx.buildTime}`;
+            const buildMeta = generateBuildMeta(ctx.version, ctx.buildTime);
             const pageHtml = layout({
                 title,
                 projectName: ctx.config.projectName,
@@ -139,8 +156,8 @@ export async function renderPost(data, i, allEntries, ctx) {
         title: data.title ?? data.slug,
         harness: data.harness ?? '',
         content: storyHtml,
-        ticketHtml: ticketRaw ? await mdToHtml(ticketRaw) : '',
-        logHtml: logRaw ? await mdToHtml(logRaw) : '',
+        ticketHtml: ticketRaw ? await mdToHtmlWithImagePathRewrite(ticketRaw) : '',
+        logHtml: logRaw ? await mdToHtmlWithImagePathRewrite(logRaw) : '',
         commits,
         version: ctx.version,
         jiraUrl,
@@ -148,7 +165,7 @@ export async function renderPost(data, i, allEntries, ctx) {
         nextEntry: next ? { slug: next.slug, title: next.title ?? '', ticket: next.ticket } : null,
     });
     const descriptionRaw = typeof data.summary === 'string' ? data.summary.replace(/[*#`]/g, '').trim() : '';
-    const buildMeta = `Generated by ${ctx.config.projectName} v${ctx.version} • ${ctx.buildTime}`;
+    const buildMeta = generateBuildMeta(ctx.version, ctx.buildTime);
     const postHtml = layout({
         title: data.title ?? data.slug,
         projectName: ctx.config.projectName,
@@ -169,3 +186,10 @@ export async function renderPost(data, i, allEntries, ctx) {
     }
     await renderLinkedMdFiles([summaryContent, ticketRaw, logRaw], entryPath, entryOutputDir, ctx);
 }
+/**
+ * Generate the standard footer metadata string.
+ * Always hardcoded to 'Project Logbook CLI' with link to npm.
+ */
+export function generateBuildMeta(version, buildTime) {
+    return `Generated by <a href="https://www.npmjs.com/package/project-logbook" target="_blank" rel="noopener noreferrer">Project Logbook CLI</a> v${version} • ${buildTime}`;
+}

package/dist/lib/git-helpers.d.ts

@@ -2,9 +2,20 @@ import type { GitCommit } from './template-types.js';
 /**
  * Parse the raw output of `git log --pretty=format:"%H|%s|%aI"` into GitCommit objects.
  * Pure function (no I/O) — unit-testable without spawning git.
+ *
+ * Uses indexOf/lastIndexOf to delimit fields so commit messages containing `|`
+ * are preserved correctly instead of being silently truncated.
  */
 export declare function parseGitLogOutput(raw: string, now?: Date): GitCommit[];
+/**
+ * Fetch git commits that touched `dir`, up to `maxCount`.
+ * Returns an empty array if git is unavailable or the directory is not a repo.
+ */
 export declare function getGitCommits(dir: string, maxCount?: number): Promise<GitCommit[]>;
+/**
+ * Fetch all git tags sorted by creation date (newest first).
+ * Returns an empty array if git is unavailable or the directory is not a repo.
+ */
 export declare function getGitTags(): Promise<{
     name: string;
     timestamp: string;

package/dist/lib/git-helpers.js

@@ -1,8 +1,14 @@
 import { execSync } from 'node:child_process';
 import { simpleGit } from 'simple-git';
+function getGit() {
+    return simpleGit(process.cwd());
+}
 /**
  * Parse the raw output of `git log --pretty=format:"%H|%s|%aI"` into GitCommit objects.
  * Pure function (no I/O) — unit-testable without spawning git.
+ *
+ * Uses indexOf/lastIndexOf to delimit fields so commit messages containing `|`
+ * are preserved correctly instead of being silently truncated.
  */
 export function parseGitLogOutput(raw, now = new Date()) {
     if (!raw.trim())
@@ -11,7 +17,13 @@ export function parseGitLogOutput(raw, now = new Date()) {
         .split('\n')
         .filter(Boolean)
         .map((line) => {
-        const [sha, message, timestamp] = line.split('|');
+        const firstPipe = line.indexOf('|');
+        const lastPipe = line.lastIndexOf('|');
+        if (firstPipe === -1 || firstPipe === lastPipe)
+            return null;
+        const sha = line.slice(0, firstPipe);
+        const message = line.slice(firstPipe + 1, lastPipe);
+        const timestamp = line.slice(lastPipe + 1);
         if (!sha || !message || !timestamp)
             return null;
         const relativeTime = formatRelativeTime(timestamp, now);
@@ -42,20 +54,31 @@ function formatRelativeTime(isoTimestamp, now) {
     const diffYear = Math.floor(diffMonth / 12);
     return `${diffYear} year${diffYear === 1 ? '' : 's'} ago`;
 }
+/**
+ * Fetch git commits that touched `dir`, up to `maxCount`.
+ * Returns an empty array if git is unavailable or the directory is not a repo.
+ */
 export async function getGitCommits(dir, maxCount = 100) {
     try {
-        const git = simpleGit(process.cwd());
-        const raw = await git.raw(['log', '--follow', `-n`, String(maxCount), '--pretty=format:%H|%s|%aI', '--', dir]);
+        const raw = await getGit().raw(['log', '--follow', `-n`, String(maxCount), '--pretty=format:%H|%s|%aI', '--', dir]);
         return parseGitLogOutput(raw);
     }
     catch {
         return [];
     }
 }
+/**
+ * Fetch all git tags sorted by creation date (newest first).
+ * Returns an empty array if git is unavailable or the directory is not a repo.
+ */
 export async function getGitTags() {
     try {
-        const git = simpleGit(process.cwd());
-        const raw = await git.raw(['tag', '-l', '--sort=-creatordate', '--format=%(creatordate:iso8601)|%(refname:short)']);
+        const raw = await getGit().raw([
+            'tag',
+            '-l',
+            '--sort=-creatordate',
+            '--format=%(creatordate:iso8601)|%(refname:short)',
+        ]);
         return raw
             .split('\n')
             .filter(Boolean)

package/dist/lib/image-helpers.d.ts

@@ -1,7 +1,11 @@
+import type { Root } from 'hast';
+import type { Plugin } from 'unified';
 /**
  * Extract image paths from markdown content
  */
 export declare function extractImagePathsFromMarkdown(content: string): string[];
+/** Rehype plugin: rewrite relative image paths to use /images/ subfolder */
+export declare const rehypeRewriteImagePaths: Plugin<[], Root>;
 /**
  * Process markdown with image collection enabled
  * Returns { html, imagePaths }

package/dist/lib/image-helpers.js

@@ -2,6 +2,7 @@ import fs from 'fs-extra';
 import { join, dirname, relative } from 'node:path';
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
 import remarkRehype from 'remark-rehype';
 import rehypeSlug from 'rehype-slug';
 import rehypeFormat from 'rehype-format';
@@ -57,6 +58,29 @@ function visitImages(node, visitor) {
         }
     }
 }
+/** Rehype plugin: rewrite relative image paths to use /images/ subfolder */
+export const rehypeRewriteImagePaths = () => {
+    return (tree) => {
+        visitImages(tree, (node) => {
+            const src = node.properties?.src;
+            if (typeof src !== 'string')
+                return;
+            // Skip external URLs and data URIs
+            if (/^[a-z][a-z\d+\-.]*:/i.test(src))
+                return;
+            if (src.startsWith('data:'))
+                return;
+            // Skip already rewritten paths
+            if (src.startsWith('./images/') || src.startsWith('../images/'))
+                return;
+            // Skip absolute paths
+            if (src.startsWith('/'))
+                return;
+            // Rewrite relative paths to use /images/ subfolder
+            node.properties.src = `./images/${src}`;
+        });
+    };
+};
 /**
  * Process markdown with image collection enabled
  * Returns { html, imagePaths }
@@ -65,8 +89,10 @@ export async function mdToHtmlWithImages(md) {
     imageProcessor.reset();
     const processorWithImages = unified()
         .use(remarkParse)
+        .use(remarkGfm)
         .use(remarkRehype)
         .use(imageProcessor.rehypeCollectImages)
+        .use(rehypeRewriteImagePaths)
         .use(rehypeSlug)
         .use(rehypeFormat)
         .use(rehypeStringify);

package/dist/lib/template-helpers.d.ts

@@ -0,0 +1,8 @@
+import type { TimelineEntry, TimelineCommitItem, TimelineTagItem, EntryLink, GitCommit } from './template-types.js';
+export declare const navLink: (entry: EntryLink, dir: "prev" | "next") => string;
+export declare const renderTagsAndWorkspaces: (tags: string[] | undefined, workspaces: string[] | undefined) => string;
+export declare const renderCommits: (commits: GitCommit[] | undefined) => string;
+export declare const renderTimelineEntryItem: (e: TimelineEntry) => string;
+export declare const renderTimelineCommitItem: (c: TimelineCommitItem, jiraBaseUrl?: string, jiraPrefix?: string) => string;
+export declare const renderTimelineTagItem: (t: TimelineTagItem) => string;
+export declare const paginationLinks: (currentPage: number, totalPages: number) => string;

package/dist/lib/template-helpers.js

@@ -0,0 +1,78 @@
+import { linkJiraIds } from './jira-helpers.js';
+const html = (strings, ...values) => {
+    return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '');
+};
+export const navLink = (entry, dir) => {
+    const label = dir === 'prev' ? '← Previous' : 'Next →';
+    const t = `${entry.ticket ? `${entry.ticket}: ` : ''}${entry.title}`;
+    return `<a href="../${entry.slug}/index.html" class="post-nav-link"><span class="post-nav-label">${label}</span><span class="post-nav-title">${t}</span></a>`;
+};
+const renderWorkspaces = (workspaces) => {
+    if (!workspaces || workspaces.length === 0)
+        return '';
+    return workspaces.map((ws) => `<span class="tag-badge tag-workspace">${ws}</span>`).join('');
+};
+export const renderTagsAndWorkspaces = (tags, workspaces) => {
+    const tagsHtml = tags && tags.length > 0
+        ? tags.map((tag) => `<span class="tag-badge tag-${tag.replace('#', '')}">${tag}</span>`).join('')
+        : '';
+    const wsHtml = renderWorkspaces(workspaces);
+    if (!tagsHtml && !wsHtml)
+        return '';
+    return html `<div class="tags-wrapper">${tagsHtml}${wsHtml}</div>`;
+};
+// Renders a compact list of git commits to embed in the Technical Log tab.
+export const renderCommits = (commits) => {
+    if (!commits || commits.length === 0)
+        return '';
+    const rows = commits
+        .map((c) => `<div class="commit-item"><span class="commit-sha">${c.sha}</span><span class="commit-message">${c.message}</span><span class="commit-time" title="${c.timestamp}">${c.relativeTime}</span></div>`)
+        .join('');
+    return `<div class="commit-list"><h3 class="commit-list-heading">Git Commits</h3>${rows}</div>`;
+};
+export const renderTimelineEntryItem = (e) => html `<div class="timeline-item" data-entry-slug="${e.slug}">
+    <a class="timeline-card" href="./${e.slug}/index.html"
+      ><div class="item-content">
+        <div class="item-meta">
+          <span data-date="${e.dateStart}">${e.displayDate}</span> • <span class="sort-time">${e.sortTime}</span> •
+          ${e.llm ? ` ${e.llm} via ` : ''}${e.harness}${e.prompter ? ` / ${e.prompter}` : ''}
+        </div>
+        <h3 class="item-title">
+          <span class="new-badge" style="display:none;">NEW</span>${e.ticket ? `${e.ticket}: ` : ''}${e.title}
+        </h3>
+        <div class="item-summary">${e.summary}</div>
+        ${renderTagsAndWorkspaces(e.tags, e.workspaces)}
+      </div>
+      <span class="item-arrow">›</span></a
+    >
+  </div>`;
+export const renderTimelineCommitItem = (c, jiraBaseUrl, jiraPrefix) => {
+    const message = jiraBaseUrl && jiraPrefix ? linkJiraIds(c.message, jiraBaseUrl, jiraPrefix) : c.message;
+    return `<div class="timeline-item timeline-item--commit"><div class="commit-chip"><span class="commit-sha">${c.sha}</span><span class="commit-message">${message}</span><span class="commit-time" title="${c.timestamp}" data-date="${c.timestamp}">${c.relativeTime}</span></div></div>`;
+};
+export const renderTimelineTagItem = (t) => {
+    const formatted = new Date(t.timestamp)
+        .toLocaleString('de-DE', {
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    })
+        .replace(',', '');
+    return `<div class="timeline-item timeline-item--tag"><div class="tag-chip"><span class="tag-chip-icon">🏷</span><span class="tag-chip-name">${t.name}</span><span class="tag-chip-date" title="${t.timestamp}">${formatted}</span></div></div>`;
+};
+export const paginationLinks = (currentPage, totalPages) => {
+    let links = '';
+    if (currentPage > 1) {
+        const prevPageLink = currentPage === 2 ? 'index.html' : `index-${currentPage - 1}.html`;
+        links += `<a href="./${prevPageLink}" class="pagination-link pagination-link--prev">← Previous Page</a>`;
+    }
+    if (currentPage < totalPages) {
+        const nextPageLink = `index-${currentPage + 1}.html`;
+        links += `<a href="./${nextPageLink}" class="pagination-link pagination-link--next">Next Page →</a>`;
+    }
+    return links ? `<nav class="pagination-nav">${links}</nav>` : '';
+};

package/dist/lib/template-types.d.ts

@@ -18,6 +18,8 @@ export interface TimelineTemplateProps {
     aboutHtml: string;
     jiraBaseUrl?: string;
     jiraPrefix?: string;
+    currentPage?: number;
+    totalPages?: number;
 }
 /**
  * Configuration for a month group in the timeline
@@ -40,6 +42,7 @@ export interface TimelineEntry {
     dateEnd?: string;
     displayDate: string;
     sortTime: string;
+    monthGroup: string;
     harness?: string;
     llm?: string;
     prompter?: string;

package/dist/lib/templates.js

@@ -1,4 +1,4 @@
-import { linkJiraIds } from './jira-helpers.js';
+import { navLink, renderTagsAndWorkspaces, renderCommits, renderTimelineEntryItem, renderTimelineCommitItem, renderTimelineTagItem, paginationLinks, } from './template-helpers.js';
 const html = (strings, ...values) => {
     return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '');
 };
@@ -28,70 +28,8 @@ export const layout = ({ title, header, content, projectName, basePath = './', d
     <footer>${buildMeta ? `<p class="build-time">${buildMeta}</p>` : ''}</footer>
     <script src="${basePath}logbook.js"></script>
 </body></html>`;
-const navLink = (entry, dir) => {
-    const label = dir === 'prev' ? '← Previous' : 'Next →';
-    const t = `${entry.ticket ? `${entry.ticket}: ` : ''}${entry.title}`;
-    return `<a href="../${entry.slug}/index.html" class="post-nav-link"><span class="post-nav-label">${label}</span><span class="post-nav-title">${t}</span></a>`;
-};
-const renderWorkspaces = (workspaces) => {
-    if (!workspaces || workspaces.length === 0)
-        return '';
-    return workspaces.map((ws) => `<span class="tag-badge tag-workspace">${ws}</span>`).join('');
-};
-const renderTagsAndWorkspaces = (tags, workspaces) => {
-    const tagsHtml = tags && tags.length > 0
-        ? tags.map((tag) => `<span class="tag-badge tag-${tag.replace('#', '')}">${tag}</span>`).join('')
-        : '';
-    const wsHtml = renderWorkspaces(workspaces);
-    if (!tagsHtml && !wsHtml)
-        return '';
-    return html `<div class="tags-wrapper">${tagsHtml}${wsHtml}</div>`;
-};
-// Renders a compact list of git commits to embed in the Technical Log tab.
-const renderCommits = (commits) => {
-    if (!commits || commits.length === 0)
-        return '';
-    const rows = commits
-        .map((c) => `<div class="commit-item"><span class="commit-sha">${c.sha}</span><span class="commit-message">${c.message}</span><span class="commit-time" title="${c.timestamp}">${c.relativeTime}</span></div>`)
-        .join('');
-    return `<div class="commit-list"><h3 class="commit-list-heading">Git Commits</h3>${rows}</div>`;
-};
-const renderTimelineEntryItem = (e) => html `<div class="timeline-item" data-entry-slug="${e.slug}">
-    <a class="timeline-card" href="./${e.slug}/index.html"
-      ><div class="item-content">
-        <div class="item-meta">
-          <span data-date="${e.dateStart}">${e.displayDate}</span> • <span class="sort-time">${e.sortTime}</span> •
-          ${e.llm ? ` ${e.llm} via ` : ''}${e.harness}${e.prompter ? ` / ${e.prompter}` : ''}
-        </div>
-        <h3 class="item-title">
-          <span class="new-badge" style="display:none;">NEW</span>${e.ticket ? `${e.ticket}: ` : ''}${e.title}
-        </h3>
-        <div class="item-summary">${e.summary}</div>
-        ${renderTagsAndWorkspaces(e.tags, e.workspaces)}
-      </div>
-      <span class="item-arrow">›</span></a
-    >
-  </div>`;
-const renderTimelineCommitItem = (c, jiraBaseUrl, jiraPrefix) => {
-    const message = jiraBaseUrl && jiraPrefix ? linkJiraIds(c.message, jiraBaseUrl, jiraPrefix) : c.message;
-    return `<div class="timeline-item timeline-item--commit"><div class="commit-chip"><span class="commit-sha">${c.sha}</span><span class="commit-message">${message}</span><span class="commit-time" title="${c.timestamp}" data-date="${c.timestamp}">${c.relativeTime}</span></div></div>`;
-};
-const renderTimelineTagItem = (t) => {
-    const formatted = new Date(t.timestamp)
-        .toLocaleString('de-DE', {
-        year: 'numeric',
-        month: '2-digit',
-        day: '2-digit',
-        hour: '2-digit',
-        minute: '2-digit',
-        second: '2-digit',
-        hour12: false,
-    })
-        .replace(',', '');
-    return `<div class="timeline-item timeline-item--tag"><div class="tag-chip"><span class="tag-chip-icon">🏷</span><span class="tag-chip-name">${t.name}</span><span class="tag-chip-date" title="${t.timestamp}">${formatted}</span></div></div>`;
-};
 export const timelineTemplate = (props) => {
-    const { projectName, groups, readmeHtml, aboutHtml, jiraBaseUrl, jiraPrefix } = props;
+    const { projectName, groups, readmeHtml, aboutHtml, jiraBaseUrl, jiraPrefix, currentPage, totalPages } = props;
     const timelineTab = html `<div class="timeline">
     ${groups
         .map((g) => html `<section class="month-group">
@@ -107,9 +45,10 @@ export const timelineTemplate = (props) => {
         .join('')}
           </section>`)
         .join('')}
+    ${paginationLinks(currentPage, totalPages)}
   </div>`;
     return html `<header>
-      <h1>${projectName}</h1>
+      <h1><a href="./index.html">${projectName}</a></h1>
       <p class="tagline">A brief summary of the recent changes to the project.</p>
     </header>
     ${tabsComponent([

package/dist/linters/frontmatter.js

@@ -42,7 +42,23 @@ const linter = {
                 });
             }
         }
-        // 3. Tags validation
+        // 3. Validate specific placeholder values
+        const placeholderFields = ['prompter', 'harness', 'llm', 'summary'];
+        for (const field of placeholderFields) {
+            const value = frontmatter[field];
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (typeof item === 'string' && (item === field.toUpperCase() || item === 'WRITE_SUMMARY_HERE')) {
+                        issues.push({
+                            level: 'error',
+                            category: 'frontmatter',
+                            message: `Placeholder value "${item}" found in field "${field}". Please replace with actual content.`,
+                        });
+                    }
+                }
+            }
+        }
+        // 4. Tags validation
         const allowedTags = config.tags?.allowed || [];
         if (!frontmatter.tags || !Array.isArray(frontmatter.tags) || frontmatter.tags.length === 0) {
             issues.push({
@@ -62,6 +78,10 @@ const linter = {
                 }
             }
         }
+        // TODO: Add conditional validation for body placeholders based on isDraft
+        // Currently the isDraft only checks frontmatter data for placeholders.
+        // If the body contains "TODO:" and isDraft is true, the current logic is to skip.
+        // However, if we want to lint placeholder values even in draft mode, we need a separate body linter.
         return issues;
     },
 };

package/dist/linters/placeholders.js

@@ -14,8 +14,6 @@ const linter = {
         if (context.indexPath && (await fs.pathExists(context.indexPath))) {
             rawFile = await fs.readFile(context.indexPath, 'utf8');
         }
-        // Scan only the frontmatter block for bracket-style placeholders to avoid false
-        // positives when placeholder names are mentioned in the narrative body.
         const frontmatterMatch = rawFile.match(/^---\n[\s\S]*?\n---/);
         const frontmatterBlock = frontmatterMatch ? frontmatterMatch[0] : rawFile;
         const frontmatterPlaceholders = [
@@ -37,7 +35,7 @@ const linter = {
                 });
             }
         }
-        // Check boilerplate body text against the full content (body only is fine here).
+        // Check boilerplate body text against the full content (body only is fine here) for all entries.
         if (context.content.includes('TODO: ')) {
             issues.push({
                 level: 'error',

package/dist/templates/CONTRIBUTING.md

@@ -37,10 +37,10 @@ As you code, keep the `log.md` updated in real-time using the `logbook log` comm
 
 ```bash
 logbook log "Investigated root cause — found issue in src/lib/config.ts"
-logbook log "Fixed the bug" "Added tests" "All passing"
+logbook log "Fixed the bug"
 ```
 
-Each message is automatically prefixed with an ISO timestamp and appended as a bullet to the active `log.md`. You may pass multiple quoted strings in one call. If you encounter a bug or change your design, log it immediately. This is the most valuable file for future debugging.
+Each message is automatically prefixed with an ISO timestamp and appended as a bullet to the active `log.md`. One message per call. If you encounter a bug or change your design, log it immediately. This is the most valuable file for future debugging.
 
 Only update the currently active logbook entry. Do not edit other existing entries while working.
 

package/dist/templates/steer.txt

@@ -11,8 +11,8 @@ Phase 2: Execute & Trace
 1. Use `log.md` as a live technical scratchpad.
 2. Log your work in real-time using the `logbook log "<message>"` command. Record every major decision, error, and pivot. Do not reconstruct this at the end.
    Example: logbook log "Investigated root cause — found issue in src/lib/config.ts"
-3. You may pass multiple messages in one call: logbook log "Msg A" "Msg B"
-4. Stick to the active entry; never modify past entries in the logbook folder.
+   One message per call. For multiple entries, call the command once per message.
+3. Stick to the active entry; never modify past entries in the logbook folder.
 
 Phase 3: Synthesize
 1. When implementation is finished, write the narrative in `index.md`.

package/dist/templates/styles.css

@@ -11,6 +11,11 @@ body {
   padding: 0;
 }
 
+.home-link {
+  text-decoration: none;
+  color: inherit;
+}
+
 header {
   background: var(--card-bg);
   border-bottom: 1px solid var(--border);
@@ -25,6 +30,11 @@ header h1 {
   letter-spacing: -0.025em;
 }
 
+header h1 a {
+  text-decoration: none !important;
+  color: black !important;
+}
+
 .tagline {
   color: var(--text-muted);
   font-size: 1.125rem;
@@ -273,6 +283,44 @@ article h1 {
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
 }
 
+/* Pagination Links */
+.pagination-nav {
+  display: flex;
+  justify-content: space-between;
+  margin-top: 2rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--border);
+}
+
+.pagination-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.9375rem;
+  font-weight: 500;
+  color: var(--primary);
+  text-decoration: none;
+  padding: 0.5rem 1rem;
+  border-radius: 2rem;
+  transition:
+    background 0.2s,
+    color 0.2s;
+  background: var(--primary-soft);
+}
+
+.pagination-link:hover {
+  background: var(--primary);
+  color: white;
+}
+
+.pagination-link--prev {
+  margin-right: auto;
+}
+
+.pagination-link--next {
+  margin-left: auto;
+}
+
 .content-section {
   animation: fadeIn 0.4s cubic-bezier(0.4, 0, 0.2, 1);
   font-size: 1.125rem;
@@ -286,6 +334,10 @@ article h1 {
   margin-bottom: 1rem;
 }
 
+.content-section img {
+  max-width: 100%;
+}
+
 @keyframes fadeIn {
   from {
     opacity: 0;

package/dist/utils/timeline-helpers.d.ts

@@ -0,0 +1,4 @@
+import { TimelineEntry, TimelineCommitItem, TimelineTagItem, TimelineGroup } from '../lib/template-types.js';
+export declare function groupTimelineItems(entries: (TimelineEntry & {
+    monthGroup: string;
+})[], commits: TimelineCommitItem[], tags: TimelineTagItem[]): TimelineGroup[];

package/dist/utils/timeline-helpers.js

@@ -0,0 +1,19 @@
+export function groupTimelineItems(entries, commits, tags) {
+    const toMs = (item) => {
+        if (item.kind === 'entry')
+            return item.dateEnd ? new Date(item.dateEnd).getTime() : new Date(item.dateStart).getTime();
+        return new Date(item.timestamp).getTime();
+    };
+    const all = [...entries, ...commits, ...tags];
+    all.sort((a, b) => toMs(b) - toMs(a));
+    const groups = [];
+    for (const item of all) {
+        let group = groups.find((g) => g.month === item.monthGroup);
+        if (!group) {
+            group = { month: item.monthGroup, items: [] };
+            groups.push(group);
+        }
+        group.items.push(item);
+    }
+    return groups;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-logbook",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A command-line tool for project logbooks.",
   "workspaces": [
     "demo-app"
@@ -28,7 +28,8 @@
     "test": "vitest run",
     "pre": "npm run format && npm run lint && npm run test && npm run build && npm run knip && npm run madge && npm run dev build && npm run dev lint",
     "next": "node scripts/create-ticket-from-backlog.js",
-    "link": "npm run build && npm link"
+    "link": "npm run build && npm link",
+    "open": "npm run build && node scripts/open-and-view-dist.js"
   },
   "keywords": [
     "logbook",
@@ -61,6 +62,7 @@
     "rehype-format": "^5.0.1",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
+    "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "simple-git": "^3.36.0",

package/src/templates/CONTRIBUTING.md

@@ -37,10 +37,10 @@ As you code, keep the `log.md` updated in real-time using the `logbook log` comm
 
 ```bash
 logbook log "Investigated root cause — found issue in src/lib/config.ts"
-logbook log "Fixed the bug" "Added tests" "All passing"
+logbook log "Fixed the bug"
 ```
 
-Each message is automatically prefixed with an ISO timestamp and appended as a bullet to the active `log.md`. You may pass multiple quoted strings in one call. If you encounter a bug or change your design, log it immediately. This is the most valuable file for future debugging.
+Each message is automatically prefixed with an ISO timestamp and appended as a bullet to the active `log.md`. One message per call. If you encounter a bug or change your design, log it immediately. This is the most valuable file for future debugging.
 
 Only update the currently active logbook entry. Do not edit other existing entries while working.
 

package/src/templates/steer.txt

@@ -11,8 +11,8 @@ Phase 2: Execute & Trace
 1. Use `log.md` as a live technical scratchpad.
 2. Log your work in real-time using the `logbook log "<message>"` command. Record every major decision, error, and pivot. Do not reconstruct this at the end.
    Example: logbook log "Investigated root cause — found issue in src/lib/config.ts"
-3. You may pass multiple messages in one call: logbook log "Msg A" "Msg B"
-4. Stick to the active entry; never modify past entries in the logbook folder.
+   One message per call. For multiple entries, call the command once per message.
+3. Stick to the active entry; never modify past entries in the logbook folder.
 
 Phase 3: Synthesize
 1. When implementation is finished, write the narrative in `index.md`.

package/src/templates/styles.css

@@ -11,6 +11,11 @@ body {
   padding: 0;
 }
 
+.home-link {
+  text-decoration: none;
+  color: inherit;
+}
+
 header {
   background: var(--card-bg);
   border-bottom: 1px solid var(--border);
@@ -25,6 +30,11 @@ header h1 {
   letter-spacing: -0.025em;
 }
 
+header h1 a {
+  text-decoration: none !important;
+  color: black !important;
+}
+
 .tagline {
   color: var(--text-muted);
   font-size: 1.125rem;
@@ -273,6 +283,44 @@ article h1 {
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
 }
 
+/* Pagination Links */
+.pagination-nav {
+  display: flex;
+  justify-content: space-between;
+  margin-top: 2rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--border);
+}
+
+.pagination-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.9375rem;
+  font-weight: 500;
+  color: var(--primary);
+  text-decoration: none;
+  padding: 0.5rem 1rem;
+  border-radius: 2rem;
+  transition:
+    background 0.2s,
+    color 0.2s;
+  background: var(--primary-soft);
+}
+
+.pagination-link:hover {
+  background: var(--primary);
+  color: white;
+}
+
+.pagination-link--prev {
+  margin-right: auto;
+}
+
+.pagination-link--next {
+  margin-left: auto;
+}
+
 .content-section {
   animation: fadeIn 0.4s cubic-bezier(0.4, 0, 0.2, 1);
   font-size: 1.125rem;
@@ -286,6 +334,10 @@ article h1 {
   margin-bottom: 1rem;
 }
 
+.content-section img {
+  max-width: 100%;
+}
+
 @keyframes fadeIn {
   from {
     opacity: 0;