From 00e6aaef99312024d2c31c491d634c0d4f85bcff Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:17:48 +0100
Subject: [PATCH 01/26] Add SimpleDoc/SimpleLog spec

---
 docs/SIMPLEDOC_SIMPLELOG_SPEC.md | 167 +++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 docs/SIMPLEDOC_SIMPLELOG_SPEC.md

diff --git a/docs/SIMPLEDOC_SIMPLELOG_SPEC.md b/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
new file mode 100644
index 0000000..aa69e99
--- /dev/null
+++ b/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
@@ -0,0 +1,167 @@
+# SimpleDoc/SimpleLog
+
+> Daily Markdown Log (DML) v1 — Specification
+
+## 1) Storage layout
+
+- **Root directory:** any path. When used inside a SimpleDoc codebase, logs SHOULD live under `docs/` or `docs/<topic>/` to remain compliant with SimpleDoc.
+- **Daily file name:** `YYYY-MM-DD.md` (local date in the chosen “primary” timezone).
+  - Example: `2025-12-01.md`
+- **Optional subdirectories** (recommended when many files):
+  - `YYYY/YYYY-MM-DD.md` or `YYYY/MM/YYYY-MM-DD.md`
+  - Example: `2025/2025-12-01.md`
+
+## 2) File encoding and newlines
+
+- MUST be UTF-8.
+- MUST use LF (`\n`) newlines.
+- SHOULD end with a trailing newline.
+
+## 3) File header
+
+First lines define the day and timezone context.
+
+Required:
+
+1. `# YYYY-MM-DD`
+2. `> TZ: <IANA timezone>`
+
+Optional (recommended):
+
+- `> Created: <ISO-8601 timestamp>`
+- `> Updated: <ISO-8601 timestamp>`
+
+Example:
+
+```md
+# 2025-12-01
+
+> TZ: Europe/Berlin
+> Created: 2025-12-01T00:00:00+01:00
+```
+
+Notes:
+
+- The file date is interpreted in the header timezone.
+- DST transitions are supported because each entry includes an offset.
+
+## 4) Time sections (hour)
+
+Entries are grouped under hour headings.
+
+- **Section heading format (required):** `## HH:00`
+  - `HH` is 24-hour, zero-padded (`00`–`23`).
+
+Example:
+
+```md
+## 09:00
+
+## 14:00
+```
+
+Rules:
+
+- SHOULD be in chronological order.
+- A section may exist with no entries.
+
+## 5) Entry format (appendable, human-readable, parseable)
+
+Each entry is a Markdown list item starting with a local-time timestamp **including timezone offset**.
+
+Required entry prefix:
+
+- `- <TIME><OFFSET> `
+
+Where:
+
+- `<TIME>` is `HH:MM` or `HH:MM:SS`
+- `<OFFSET>` is `Z` or `±HH:MM` (e.g., `+01:00`, `-05:00`)
+
+Recommended entry body conventions (all optional):
+
+- Severity token: `[INFO]`, `[WARN]`, `[ERROR]`, etc.
+- Tags: `#tag` tokens
+- Key-values: `key=value` tokens (values may be quoted)
+
+Examples:
+
+```md
+- 09:13+01:00 Standup notes #team
+- 09:14:10+01:00 [WARN] API latency spike service=orders p95_ms=840
+- 14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
+```
+
+Multiline entries:
+
+- Continuation lines MUST be indented by two spaces (or more) to remain inside the list item.
+
+Example:
+
+```md
+- 14:27:05+01:00 Incident review #ops
+  - suspected cause: cache stampede
+  - mitigation: rate-limit + warmup
+```
+
+## 6) Deriving a full timestamp
+
+Given:
+
+- file date `YYYY-MM-DD`
+- entry prefix `HH:MM[:SS]±HH:MM`
+
+The full timestamp is:
+
+- `YYYY-MM-DDTHH:MM[:SS]±HH:MM`
+
+Example:
+
+- File: `2025-12-01.md`
+- Entry: `- 09:14:10+01:00 ...`
+- Full timestamp: `2025-12-01T09:14:10+01:00`
+
+## 7) CLI append behavior (normative)
+
+When the CLI writes an entry:
+
+1. Determine “now” in the primary timezone from the header (or CLI config).
+2. Select file by the local date in that timezone: `YYYY-MM-DD.md`.
+3. If the file does not exist, create it with the required header.
+4. Select section by local hour: `## HH:00`.
+5. Append-only behavior:
+   - If the last hour section in the file is not `HH:00`, append a new `## HH:00` at the end.
+   - Append the new entry as the last line in the current section (i.e., at file end after the section header and any existing entries).
+
+This guarantees the tool only appends (no in-file insertion) while keeping hour grouping.
+
+## 8) Complete example file
+
+`2025-12-01.md`
+
+```md
+# 2025-12-01
+
+> TZ: Europe/Berlin
+> Created: 2025-12-01T00:00:00+01:00
+
+## 09:00
+
+- 09:13:42+01:00 Checked alerts #ops
+- 09:14:10+01:00 [WARN] Elevated error rate service=api code=502
+  notes="started after deploy"
+
+## 14:00
+
+- 14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
+- 14:27:05+01:00 Incident review #ops
+  - suspected cause: cache stampede
+  - mitigation: rate-limit + warmup
+```
+
+## 9) Multiple timezones in one file (optional)
+
+If you need multiple timezones in one file (rare, but possible):
+
+- Keep the header TZ as the default.
+- Allow an optional zone ID after the offset, e.g. `- 10:00:00+01:00 Europe/Berlin ...`.

From e5f39fc032001302f4b0fec8f3bfab9f36020afa Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:18:31 +0100
Subject: [PATCH 02/26] Normalize SimpleLog spec

---
 docs/SIMPLEDOC_SIMPLELOG_SPEC.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/SIMPLEDOC_SIMPLELOG_SPEC.md b/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
index aa69e99..8f167bc 100644
--- a/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
+++ b/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
@@ -1,11 +1,11 @@
 # SimpleDoc/SimpleLog
 
-> Daily Markdown Log (DML) v1 — Specification
+> Daily Markdown Log (DML) v1 - Specification
 
 ## 1) Storage layout
 
 - **Root directory:** any path. When used inside a SimpleDoc codebase, logs SHOULD live under `docs/` or `docs/<topic>/` to remain compliant with SimpleDoc.
-- **Daily file name:** `YYYY-MM-DD.md` (local date in the chosen “primary” timezone).
+- **Daily file name:** `YYYY-MM-DD.md` (local date in the chosen "primary" timezone).
   - Example: `2025-12-01.md`
 - **Optional subdirectories** (recommended when many files):
   - `YYYY/YYYY-MM-DD.md` or `YYYY/MM/YYYY-MM-DD.md`
@@ -50,7 +50,7 @@ Notes:
 Entries are grouped under hour headings.
 
 - **Section heading format (required):** `## HH:00`
-  - `HH` is 24-hour, zero-padded (`00`–`23`).
+  - `HH` is 24-hour, zero-padded (`00-23`).
 
 Example:
 
@@ -76,7 +76,7 @@ Required entry prefix:
 Where:
 
 - `<TIME>` is `HH:MM` or `HH:MM:SS`
-- `<OFFSET>` is `Z` or `±HH:MM` (e.g., `+01:00`, `-05:00`)
+- `<OFFSET>` is `Z` or `+HH:MM` or `-HH:MM` (e.g., `+01:00`, `-05:00`)
 
 Recommended entry body conventions (all optional):
 
@@ -109,7 +109,7 @@ Example:
 Given:
 
 - file date `YYYY-MM-DD`
-- entry prefix `HH:MM[:SS]±HH:MM`
+- entry prefix `HH:MM[:SS]+HH:MM` or `HH:MM[:SS]-HH:MM`
 
 The full timestamp is:
 
@@ -125,7 +125,7 @@ Example:
 
 When the CLI writes an entry:
 
-1. Determine “now” in the primary timezone from the header (or CLI config).
+1. Determine "now" in the primary timezone from the header (or CLI config).
 2. Select file by the local date in that timezone: `YYYY-MM-DD.md`.
 3. If the file does not exist, create it with the required header.
 4. Select section by local hour: `## HH:00`.

From fc2cf1d85ffdd4d5325a06cfd7cf4ccbbaf0b33b Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:18:57 +0100
Subject: [PATCH 03/26] Remove non-ASCII from SimpleLog spec

---
 docs/SIMPLEDOC_SIMPLELOG_SPEC.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/SIMPLEDOC_SIMPLELOG_SPEC.md b/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
index 8f167bc..a7ecf8d 100644
--- a/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
+++ b/docs/SIMPLEDOC_SIMPLELOG_SPEC.md
@@ -113,7 +113,7 @@ Given:
 
 The full timestamp is:
 
-- `YYYY-MM-DDTHH:MM[:SS]±HH:MM`
+- `YYYY-MM-DDTHH:MM[:SS]+HH:MM` or `YYYY-MM-DDTHH:MM[:SS]-HH:MM`
 
 Example:
 

From 04581a071639b81c1055ff6bc935c5aa8d178f32 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:22:09 +0100
Subject: [PATCH 04/26] Rename SimpleLog spec file

---
 docs/{SIMPLEDOC_SIMPLELOG_SPEC.md => SIMPLELOG_SPEC.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/{SIMPLEDOC_SIMPLELOG_SPEC.md => SIMPLELOG_SPEC.md} (100%)

diff --git a/docs/SIMPLEDOC_SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
similarity index 100%
rename from docs/SIMPLEDOC_SIMPLELOG_SPEC.md
rename to docs/SIMPLELOG_SPEC.md

From ee37b6c40bd77c4857f5aa89d691d210fbc036ec Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:24:09 +0100
Subject: [PATCH 05/26] Align SimpleLog spec title

---
 docs/SIMPLELOG_SPEC.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index a7ecf8d..861efe3 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -1,6 +1,6 @@
-# SimpleDoc/SimpleLog
+# SimpleLog
 
-> Daily Markdown Log (DML) v1 - Specification
+> SimpleDoc subspec: Daily Markdown Log (DML) v1 - Specification
 
 ## 1) Storage layout
 

From 9dff3bccb6a8f95137d9fa53bfc5d6ec7b7d62ad Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:35:39 +0100
Subject: [PATCH 06/26] Add simpledoc log command

---
 docs/SIMPLELOG_SPEC.md  |   1 +
 docs/logs/2026-02-04.md |   8 ++
 src/cli/index.ts        |  20 +++++
 src/cli/log.ts          | 171 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 200 insertions(+)
 create mode 100644 docs/logs/2026-02-04.md
 create mode 100644 src/cli/log.ts

diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index 861efe3..5571a4e 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -132,6 +132,7 @@ When the CLI writes an entry:
 5. Append-only behavior:
    - If the last hour section in the file is not `HH:00`, append a new `## HH:00` at the end.
    - Append the new entry as the last line in the current section (i.e., at file end after the section header and any existing entries).
+   - A CLI MAY start a new `## HH:00` section when the last entry is older than a configurable threshold (for example, 5 minutes) to separate sessions, even if the hour has not changed.
 
 This guarantees the tool only appends (no in-file insertion) while keeping hour grouping.
 
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
new file mode 100644
index 0000000..15dec93
--- /dev/null
+++ b/docs/logs/2026-02-04.md
@@ -0,0 +1,8 @@
+# 2026-02-04
+
+> TZ: Europe/Berlin
+> Created: 2026-02-04T20:35:26+01:00
+
+## 20:00
+
+- 20:35:26+01:00 Implemented simpledoc log command with auto timezone/date and thresholded sections; writing this entry to document the work.
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 9d9cf67..481c00f 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -3,6 +3,7 @@ import { Command, CommanderError } from "commander";
 
 import { runCheck } from "./check.js";
 import { runInstall } from "./install.js";
+import { runLog } from "./log.js";
 import { runMigrate } from "./migrate.js";
 
 type MigrateOptions = {
@@ -15,6 +16,10 @@ type InstallOptions = {
   dryRun: boolean;
   yes: boolean;
 };
+type LogOptions = {
+  root?: string;
+  thresholdMinutes: string;
+};
 
 function getErrorMessage(err: unknown): string {
   if (err instanceof Error) return err.message;
@@ -75,6 +80,21 @@ export async function runCli(argv: string[]): Promise<void> {
       await runCheck();
     });
 
+  program
+    .command("log")
+    .description("Append a SimpleLog entry (Daily Markdown Log) to docs/logs.")
+    .argument("<message...>", "Entry text to append")
+    .option("--root <dir>", "Root directory for log files (default: docs/logs)")
+    .option(
+      "--threshold-minutes <minutes>",
+      "Start a new time section if the last entry is older than this (default: 5). Use 0 to disable.",
+      "5",
+    )
+    .action(async (messageParts: string[], options: LogOptions) => {
+      const message = messageParts.join(" ");
+      await runLog(message, options);
+    });
+
   const rest = argv.slice(2);
   const argvToParse = shouldDefaultToMigrate(rest)
     ? [...argv.slice(0, 2), "migrate", ...rest]
diff --git a/src/cli/log.ts b/src/cli/log.ts
new file mode 100644
index 0000000..c48492b
--- /dev/null
+++ b/src/cli/log.ts
@@ -0,0 +1,171 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { createGitClient } from "../git.js";
+
+type LogOptions = {
+  root?: string;
+  thresholdMinutes: number | string;
+};
+
+type LogClock = {
+  timeZone: string;
+  date: string;
+  time: string;
+  offset: string;
+};
+
+const ENTRY_RE = /^-\s+(\d{2}:\d{2}(?::\d{2})?)(Z|[+-]\d{2}:\d{2})\b/;
+const SECTION_RE = /^##\s+(\d{2}):00\s*$/;
+
+function getErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+function pad2(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+function formatOffset(offsetMinutes: number): string {
+  if (offsetMinutes === 0) return "Z";
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const abs = Math.abs(offsetMinutes);
+  const hours = Math.floor(abs / 60);
+  const minutes = abs % 60;
+  return `${sign}${pad2(hours)}:${pad2(minutes)}`;
+}
+
+function parseThresholdMinutes(value: number | string): number {
+  if (typeof value === "number") {
+    if (Number.isFinite(value) && value >= 0) return value;
+  } else if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+      const parsed = Number(trimmed);
+      if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+    }
+  }
+  throw new Error("--threshold-minutes must be a number >= 0");
+}
+
+async function getBaseDir(): Promise<string> {
+  const git = createGitClient();
+  try {
+    return await git.getRepoRoot(process.cwd());
+  } catch {
+    return process.cwd();
+  }
+}
+
+function getLocalClock(now: Date): LogClock {
+  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  const useUTC = timeZone === "UTC";
+  const year = useUTC ? now.getUTCFullYear() : now.getFullYear();
+  const month = useUTC ? now.getUTCMonth() + 1 : now.getMonth() + 1;
+  const day = useUTC ? now.getUTCDate() : now.getDate();
+  const hour = useUTC ? now.getUTCHours() : now.getHours();
+  const minute = useUTC ? now.getUTCMinutes() : now.getMinutes();
+  const second = useUTC ? now.getUTCSeconds() : now.getSeconds();
+  const offsetMinutes = useUTC ? 0 : -now.getTimezoneOffset();
+
+  const date = `${year}-${pad2(month)}-${pad2(day)}`;
+  const time = `${pad2(hour)}:${pad2(minute)}:${pad2(second)}`;
+  const offset = formatOffset(offsetMinutes);
+
+  return { timeZone, date, time, offset };
+}
+
+function findLastSection(lines: string[]): string | null {
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i] ?? "";
+    const match = line.match(SECTION_RE);
+    if (match) return `## ${match[1]}:00`;
+  }
+  return null;
+}
+
+function findLastEntryTime(lines: string[], date: string): Date | null {
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i] ?? "";
+    const match = line.match(ENTRY_RE);
+    if (!match) continue;
+    const time = match[1];
+    const offset = match[2];
+    const iso = `${date}T${time}${offset}`;
+    const parsed = new Date(iso);
+    if (!Number.isNaN(parsed.getTime())) return parsed;
+  }
+  return null;
+}
+
+function ensureTrailingNewline(text: string): string {
+  if (text === "") return "";
+  return text.endsWith("\n") ? text : `${text}\n`;
+}
+
+function buildHeader(clock: LogClock): string {
+  const created = `${clock.date}T${clock.time}${clock.offset}`;
+  return `# ${clock.date}\n> TZ: ${clock.timeZone}\n> Created: ${created}\n\n`;
+}
+
+export async function runLog(
+  message: string,
+  options: LogOptions,
+): Promise<void> {
+  try {
+    const trimmed = message.trim();
+    if (!trimmed) throw new Error("Log entry message is required.");
+
+    const thresholdMinutes = parseThresholdMinutes(options.thresholdMinutes);
+    const now = new Date();
+    const clock = getLocalClock(now);
+
+    const baseDir = await getBaseDir();
+    const rootDir = options.root
+      ? path.resolve(baseDir, options.root)
+      : path.join(baseDir, "docs", "logs");
+
+    await fs.mkdir(rootDir, { recursive: true });
+
+    const filePath = path.join(rootDir, `${clock.date}.md`);
+    let content = "";
+    let fileExists = false;
+
+    try {
+      content = await fs.readFile(filePath, "utf8");
+      fileExists = true;
+    } catch (err) {
+      if (!(err instanceof Error) || !("code" in err) || err.code !== "ENOENT")
+        throw err;
+    }
+
+    if (!fileExists) content = buildHeader(clock);
+
+    const lines = content.split(/\r?\n/);
+    const currentSection = `## ${clock.time.slice(0, 2)}:00`;
+    const lastSection = findLastSection(lines);
+    const lastEntry = findLastEntryTime(lines, clock.date);
+
+    let needsSection = false;
+    if (!lastSection || lastSection !== currentSection) needsSection = true;
+
+    if (!needsSection && thresholdMinutes > 0 && lastEntry) {
+      const diffMs = now.getTime() - lastEntry.getTime();
+      if (diffMs >= thresholdMinutes * 60_000) needsSection = true;
+    }
+
+    let nextContent = ensureTrailingNewline(content);
+    if (needsSection) nextContent += `${currentSection}\n`;
+
+    const entryLine = `- ${clock.time}${clock.offset} ${trimmed}`;
+    nextContent += `${entryLine}\n`;
+
+    await fs.writeFile(filePath, nextContent, "utf8");
+    process.stdout.write(`Logged to ${filePath}\n`);
+  } catch (err) {
+    process.stderr.write(`${getErrorMessage(err)}\n`);
+    process.exitCode = 1;
+  }
+}

From d777eee9d709f11a41633a5a625c7356e933d25a Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:39:47 +0100
Subject: [PATCH 07/26] Support multiline simpledoc log entries

---
 docs/SIMPLELOG_SPEC.md  |  1 +
 docs/logs/2026-02-04.md |  3 +++
 src/cli/index.ts        | 25 +++++++++++++++++++++++--
 src/cli/log.ts          | 13 ++++++++++++-
 4 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index 5571a4e..d6ca95f 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -95,6 +95,7 @@ Examples:
 Multiline entries:
 
 - Continuation lines MUST be indented by two spaces (or more) to remain inside the list item.
+- CLI implementations SHOULD indent newline characters from user input by two spaces so multiline entries remain valid list items.
 
 Example:
 
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 15dec93..74d5082 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -6,3 +6,6 @@
 ## 20:00
 
 - 20:35:26+01:00 Implemented simpledoc log command with auto timezone/date and thresholded sections; writing this entry to document the work.
+- 20:39:32+01:00 Added multiline support to simpledoc log.
+  - CLI now accepts --stdin and preserves newline content with proper indentation.
+  - Spec updated to mention CLI indentation for multiline input.
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 481c00f..868654b 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -19,6 +19,7 @@ type InstallOptions = {
 type LogOptions = {
   root?: string;
   thresholdMinutes: string;
+  stdin?: boolean;
 };
 
 function getErrorMessage(err: unknown): string {
@@ -37,6 +38,22 @@ function shouldDefaultToMigrate(argvRest: string[]): boolean {
   return restWithoutHelp.length > 0;
 }
 
+async function readStdinMessage(fallback: string): Promise<string> {
+  const chunks: string[] = [];
+  return await new Promise((resolve, reject) => {
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      chunks.push(String(chunk));
+    });
+    process.stdin.on("error", reject);
+    process.stdin.on("end", () => {
+      const combined = chunks.join("");
+      const trimmed = combined.trim();
+      resolve(trimmed.length > 0 ? combined : fallback);
+    });
+  });
+}
+
 export async function runCli(argv: string[]): Promise<void> {
   const program = new Command();
   program
@@ -83,15 +100,19 @@ export async function runCli(argv: string[]): Promise<void> {
   program
     .command("log")
     .description("Append a SimpleLog entry (Daily Markdown Log) to docs/logs.")
-    .argument("<message...>", "Entry text to append")
+    .argument("[message...]", "Entry text to append")
     .option("--root <dir>", "Root directory for log files (default: docs/logs)")
+    .option("--stdin", "Read entry text from stdin (supports multiline)")
     .option(
       "--threshold-minutes <minutes>",
       "Start a new time section if the last entry is older than this (default: 5). Use 0 to disable.",
       "5",
     )
     .action(async (messageParts: string[], options: LogOptions) => {
-      const message = messageParts.join(" ");
+      let message = messageParts.join(" ");
+      if (options.stdin) {
+        message = await readStdinMessage(message);
+      }
       await runLog(message, options);
     });
 
diff --git a/src/cli/log.ts b/src/cli/log.ts
index c48492b..0187a0d 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -110,6 +110,16 @@ function buildHeader(clock: LogClock): string {
   return `# ${clock.date}\n> TZ: ${clock.timeZone}\n> Created: ${created}\n\n`;
 }
 
+function formatEntryBody(message: string): string {
+  const normalized = message.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+  const lines = normalized.split("\n");
+  if (lines.length === 0) return "";
+  const [first, ...rest] = lines;
+  if (rest.length === 0) return first ?? "";
+  const indented = rest.map((line) => `  ${line}`);
+  return [first ?? "", ...indented].join("\n");
+}
+
 export async function runLog(
   message: string,
   options: LogOptions,
@@ -159,7 +169,8 @@ export async function runLog(
     let nextContent = ensureTrailingNewline(content);
     if (needsSection) nextContent += `${currentSection}\n`;
 
-    const entryLine = `- ${clock.time}${clock.offset} ${trimmed}`;
+    const entryBody = formatEntryBody(trimmed);
+    const entryLine = `- ${clock.time}${clock.offset} ${entryBody}`;
     nextContent += `${entryLine}\n`;
 
     await fs.writeFile(filePath, nextContent, "utf8");

From a3ee554db7700e781b37b54e3d5b2bfd99019f18 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:42:05 +0100
Subject: [PATCH 08/26] Auto-read stdin for simpledoc log

---
 src/cli/index.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/cli/index.ts b/src/cli/index.ts
index 868654b..5a3f616 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -102,7 +102,10 @@ export async function runCli(argv: string[]): Promise<void> {
     .description("Append a SimpleLog entry (Daily Markdown Log) to docs/logs.")
     .argument("[message...]", "Entry text to append")
     .option("--root <dir>", "Root directory for log files (default: docs/logs)")
-    .option("--stdin", "Read entry text from stdin (supports multiline)")
+    .option(
+      "--stdin",
+      "Read entry text from stdin (supports multiline). If stdin is piped, it is read automatically.",
+    )
     .option(
       "--threshold-minutes <minutes>",
       "Start a new time section if the last entry is older than this (default: 5). Use 0 to disable.",
@@ -110,7 +113,7 @@ export async function runCli(argv: string[]): Promise<void> {
     )
     .action(async (messageParts: string[], options: LogOptions) => {
       let message = messageParts.join(" ");
-      if (options.stdin) {
+      if (options.stdin || !process.stdin.isTTY) {
         message = await readStdinMessage(message);
       }
       await runLog(message, options);

From c189f6896eea57d59e4194382de94eef38b4fcf6 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 20:54:45 +0100
Subject: [PATCH 09/26] Revise SimpleLog format and frontmatter

---
 docs/SIMPLELOG_SPEC.md  | 115 ++++++++++--------
 docs/logs/2026-02-04.md |  22 ++--
 src/cli/log.ts          | 253 +++++++++++++++++++++++++++++++++++-----
 3 files changed, 303 insertions(+), 87 deletions(-)

diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index d6ca95f..1fa6b8f 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -17,47 +17,52 @@
 - MUST use LF (`\n`) newlines.
 - SHOULD end with a trailing newline.
 
-## 3) File header
+## 3) Frontmatter (required)
 
-First lines define the day and timezone context.
+Files MUST start with YAML frontmatter that follows SimpleDoc conventions.
 
-Required:
+Required fields:
 
-1. `# YYYY-MM-DD`
-2. `> TZ: <IANA timezone>`
+- `title`: human-readable title for the day.
+- `author`: `Name <email>` (RFC 5322 name-addr format).
+- `date`: `YYYY-MM-DD`.
+- `tz`: IANA timezone ID (e.g., `Europe/Berlin`).
+- `created`: ISO-8601 timestamp with offset.
 
-Optional (recommended):
+Optional fields:
 
-- `> Created: <ISO-8601 timestamp>`
-- `> Updated: <ISO-8601 timestamp>`
+- `updated`: ISO-8601 timestamp with offset.
 
 Example:
 
 ```md
-# 2025-12-01
-
-> TZ: Europe/Berlin
-> Created: 2025-12-01T00:00:00+01:00
+---
+title: Daily Log 2025-12-01
+author: Jane Doe <jane@example.com>
+date: 2025-12-01
+tz: Europe/Berlin
+created: 2025-12-01T00:00:00+01:00
+---
 ```
 
 Notes:
 
-- The file date is interpreted in the header timezone.
+- The file date is interpreted in the `tz` timezone.
 - DST transitions are supported because each entry includes an offset.
 
-## 4) Time sections (hour)
+## 4) Session sections (threshold)
 
-Entries are grouped under hour headings.
+Entries are grouped into session sections. Section titles SHOULD reflect the local time of the first entry in that section.
 
-- **Section heading format (required):** `## HH:00`
+- **Section heading format (required):** `## HH:MM`
   - `HH` is 24-hour, zero-padded (`00-23`).
 
 Example:
 
 ```md
-## 09:00
+## 09:13
 
-## 14:00
+## 14:03
 ```
 
 Rules:
@@ -67,11 +72,11 @@ Rules:
 
 ## 5) Entry format (appendable, human-readable, parseable)
 
-Each entry is a Markdown list item starting with a local-time timestamp **including timezone offset**.
+Each entry is a single line starting with a local-time timestamp **including timezone offset**.
 
 Required entry prefix:
 
-- `- <TIME><OFFSET> `
+- `<TIME><OFFSET> `
 
 Where:
 
@@ -87,22 +92,23 @@ Recommended entry body conventions (all optional):
 Examples:
 
 ```md
-- 09:13+01:00 Standup notes #team
-- 09:14:10+01:00 [WARN] API latency spike service=orders p95_ms=840
-- 14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
+09:13+01:00 Standup notes #team
+09:14:10+01:00 [WARN] API latency spike service=orders p95_ms=840
+14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
 ```
 
 Multiline entries:
 
-- Continuation lines MUST be indented by two spaces (or more) to remain inside the list item.
-- CLI implementations SHOULD indent newline characters from user input by two spaces so multiline entries remain valid list items.
+- Continuation lines MUST be indented by two spaces (or more) to remain associated with the entry above.
+- CLI implementations SHOULD indent newline characters from user input by two spaces so multiline entries remain valid.
 
 Example:
 
 ```md
-- 14:27:05+01:00 Incident review #ops
-  - suspected cause: cache stampede
-  - mitigation: rate-limit + warmup
+14:27:05+01:00 Incident review #ops
+
+- suspected cause: cache stampede
+- mitigation: rate-limit + warmup
 ```
 
 ## 6) Deriving a full timestamp
@@ -119,51 +125,58 @@ The full timestamp is:
 Example:
 
 - File: `2025-12-01.md`
-- Entry: `- 09:14:10+01:00 ...`
+- Entry: `09:14:10+01:00 ...`
 - Full timestamp: `2025-12-01T09:14:10+01:00`
 
 ## 7) CLI append behavior (normative)
 
 When the CLI writes an entry:
 
-1. Determine "now" in the primary timezone from the header (or CLI config).
+1. Determine "now" in the primary timezone from frontmatter (or CLI config).
 2. Select file by the local date in that timezone: `YYYY-MM-DD.md`.
-3. If the file does not exist, create it with the required header.
-4. Select section by local hour: `## HH:00`.
-5. Append-only behavior:
-   - If the last hour section in the file is not `HH:00`, append a new `## HH:00` at the end.
-   - Append the new entry as the last line in the current section (i.e., at file end after the section header and any existing entries).
-   - A CLI MAY start a new `## HH:00` section when the last entry is older than a configurable threshold (for example, 5 minutes) to separate sessions, even if the hour has not changed.
+3. If the file does not exist, create it with the required frontmatter.
+4. Start a new session section when either:
+   - no section exists yet, or
+   - the last entry is older than the threshold (for example, 5 minutes).
+     The new section title MUST be the current local time in `HH:MM` format.
+5. Append the new entry as the last line in the current section, indenting multiline input by two spaces.
 
-This guarantees the tool only appends (no in-file insertion) while keeping hour grouping.
+This guarantees the tool only appends (no in-file insertion) while keeping session grouping.
 
 ## 8) Complete example file
 
 `2025-12-01.md`
 
 ```md
-# 2025-12-01
+---
+title: Daily Log 2025-12-01
+author: Jane Doe <jane@example.com>
+date: 2025-12-01
+tz: Europe/Berlin
+created: 2025-12-01T00:00:00+01:00
+---
+
+## 09:13
+
+09:13:42+01:00 Checked alerts #ops
+09:14:10+01:00 [WARN] Elevated error rate service=api code=502
+notes="started after deploy"
 
-> TZ: Europe/Berlin
-> Created: 2025-12-01T00:00:00+01:00
+## 14:03
 
-## 09:00
+14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
 
-- 09:13:42+01:00 Checked alerts #ops
-- 09:14:10+01:00 [WARN] Elevated error rate service=api code=502
-  notes="started after deploy"
+## 14:27
 
-## 14:00
+14:27:05+01:00 Incident review #ops
 
-- 14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
-- 14:27:05+01:00 Incident review #ops
-  - suspected cause: cache stampede
-  - mitigation: rate-limit + warmup
+- suspected cause: cache stampede
+- mitigation: rate-limit + warmup
 ```
 
 ## 9) Multiple timezones in one file (optional)
 
 If you need multiple timezones in one file (rare, but possible):
 
-- Keep the header TZ as the default.
-- Allow an optional zone ID after the offset, e.g. `- 10:00:00+01:00 Europe/Berlin ...`.
+- Keep the frontmatter `tz` as the default.
+- Allow an optional zone ID after the offset, e.g. `10:00:00+01:00 Europe/Berlin ...`.
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 74d5082..f9e38c9 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -1,11 +1,17 @@
-# 2026-02-04
+---
+title: Daily Log 2026-02-04
+author: Onur Solmaz <info@solmaz.io>
+date: 2026-02-04
+tz: Europe/Berlin
+created: 2026-02-04T20:35:26+01:00
+---
 
-> TZ: Europe/Berlin
-> Created: 2026-02-04T20:35:26+01:00
+## 20:35
 
-## 20:00
+20:35:26+01:00 Implemented simpledoc log command with auto timezone/date and thresholded sections; writing this entry to document the work.
+20:39:32+01:00 Added multiline support to simpledoc log.
 
-- 20:35:26+01:00 Implemented simpledoc log command with auto timezone/date and thresholded sections; writing this entry to document the work.
-- 20:39:32+01:00 Added multiline support to simpledoc log.
-  - CLI now accepts --stdin and preserves newline content with proper indentation.
-  - Spec updated to mention CLI indentation for multiline input.
+- CLI now accepts --stdin and preserves newline content with proper indentation.
+- Spec updated to mention CLI indentation for multiline input.
+  20:43:06+01:00 Auto-read stdin for simpledoc log when piped, matching Unix utility expectations.
+- Kept --stdin for explicit use.
diff --git a/src/cli/log.ts b/src/cli/log.ts
index 0187a0d..3a65c59 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -16,8 +16,14 @@ type LogClock = {
   offset: string;
 };
 
-const ENTRY_RE = /^-\s+(\d{2}:\d{2}(?::\d{2})?)(Z|[+-]\d{2}:\d{2})\b/;
-const SECTION_RE = /^##\s+(\d{2}):00\s*$/;
+type Frontmatter = {
+  data: Record<string, string>;
+  body: string;
+  hasFrontmatter: boolean;
+};
+
+const ENTRY_RE = /^-?\s*(\d{2}:\d{2}(?::\d{2})?)(Z|[+-]\d{2}:\d{2})\b/;
+const SECTION_RE = /^##\s+(\d{2}):(\d{2})(?::\d{2})?\s*$/;
 
 function getErrorMessage(err: unknown): string {
   if (err instanceof Error) return err.message;
@@ -59,29 +65,176 @@ async function getBaseDir(): Promise<string> {
   }
 }
 
-function getLocalClock(now: Date): LogClock {
-  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
-  const useUTC = timeZone === "UTC";
-  const year = useUTC ? now.getUTCFullYear() : now.getFullYear();
-  const month = useUTC ? now.getUTCMonth() + 1 : now.getMonth() + 1;
-  const day = useUTC ? now.getUTCDate() : now.getDate();
-  const hour = useUTC ? now.getUTCHours() : now.getHours();
-  const minute = useUTC ? now.getUTCMinutes() : now.getMinutes();
-  const second = useUTC ? now.getUTCSeconds() : now.getSeconds();
-  const offsetMinutes = useUTC ? 0 : -now.getTimezoneOffset();
+function getDefaultTimeZone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+
+function getClockForTimeZone(now: Date, timeZone: string): LogClock {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+
+  const parts = formatter.formatToParts(now);
+  const lookup = (type: string): string =>
+    parts.find((part) => part.type === type)?.value ?? "";
+
+  const year = Number(lookup("year"));
+  const month = Number(lookup("month"));
+  const day = Number(lookup("day"));
+  const hour = Number(lookup("hour"));
+  const minute = Number(lookup("minute"));
+  const second = Number(lookup("second"));
+
+  if (!year || !month || !day) {
+    throw new Error(`Failed to derive date parts for timezone ${timeZone}`);
+  }
 
   const date = `${year}-${pad2(month)}-${pad2(day)}`;
   const time = `${pad2(hour)}:${pad2(minute)}:${pad2(second)}`;
+  const asUtc = Date.UTC(year, month - 1, day, hour, minute, second);
+  const offsetMinutes = Math.round((asUtc - now.getTime()) / 60_000);
   const offset = formatOffset(offsetMinutes);
 
   return { timeZone, date, time, offset };
 }
 
+function safeClockForTimeZone(now: Date, timeZone: string): LogClock | null {
+  try {
+    return getClockForTimeZone(now, timeZone);
+  } catch {
+    return null;
+  }
+}
+
+function parseFrontmatter(content: string): Frontmatter {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== "---") {
+    return { data: {}, body: content, hasFrontmatter: false };
+  }
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i] === "---") {
+      end = i;
+      break;
+    }
+  }
+
+  if (end === -1) {
+    return { data: {}, body: content, hasFrontmatter: false };
+  }
+
+  const data: Record<string, string> = {};
+  for (const line of lines.slice(1, end)) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) data[match[1]] = match[2];
+  }
+
+  const body = lines.slice(end + 1).join("\n");
+  return { data, body, hasFrontmatter: true };
+}
+
+function stripLegacyHeader(content: string): string {
+  const lines = content.split(/\r?\n/);
+  if (!/^#\s+\d{4}-\d{2}-\d{2}\s*$/.test(lines[0] ?? "")) return content;
+
+  let idx = 1;
+  while (idx < lines.length) {
+    const line = lines[idx] ?? "";
+    if (line.trim() === "") {
+      idx += 1;
+      continue;
+    }
+    if (line.trim().startsWith(">")) {
+      idx += 1;
+      continue;
+    }
+    break;
+  }
+
+  return lines.slice(idx).join("\n");
+}
+
+function buildFrontmatter(data: Record<string, string>): string {
+  const preferredOrder = [
+    "title",
+    "author",
+    "date",
+    "tz",
+    "created",
+    "updated",
+  ];
+  const preferred = preferredOrder.filter((key) => key in data);
+  const extras = Object.keys(data)
+    .filter((key) => !preferredOrder.includes(key))
+    .sort();
+  const keys = [...preferred, ...extras];
+  const lines = keys
+    .map((key) => `${key}: ${data[key]}`)
+    .filter((line) => !line.endsWith(": "));
+  return `---\n${lines.join("\n")}\n---\n\n`;
+}
+
+function resolveAuthor(): string {
+  const name =
+    process.env.GIT_AUTHOR_NAME ||
+    process.env.GIT_COMMITTER_NAME ||
+    process.env.USER ||
+    "Unknown";
+  const email =
+    process.env.GIT_AUTHOR_EMAIL ||
+    process.env.GIT_COMMITTER_EMAIL ||
+    process.env.EMAIL ||
+    "unknown@example.com";
+
+  if (name.includes("<") && name.includes(">")) return name;
+  return `${name} <${email}>`;
+}
+
+function normalizeFrontmatter(
+  data: Record<string, string>,
+  clock: LogClock,
+  author: string,
+): { data: Record<string, string>; changed: boolean } {
+  const next = { ...data };
+  let changed = false;
+
+  if (!next.title) {
+    next.title = `Daily Log ${clock.date}`;
+    changed = true;
+  }
+  if (!next.author) {
+    next.author = author;
+    changed = true;
+  }
+  if (!next.date) {
+    next.date = clock.date;
+    changed = true;
+  }
+  if (!next.tz) {
+    next.tz = clock.timeZone;
+    changed = true;
+  }
+  if (!next.created) {
+    next.created = `${clock.date}T${clock.time}${clock.offset}`;
+    changed = true;
+  }
+
+  return { data: next, changed };
+}
+
 function findLastSection(lines: string[]): string | null {
   for (let i = lines.length - 1; i >= 0; i -= 1) {
     const line = lines[i] ?? "";
     const match = line.match(SECTION_RE);
-    if (match) return `## ${match[1]}:00`;
+    if (match) return `## ${match[1]}:${match[2]}`;
   }
   return null;
 }
@@ -105,9 +258,10 @@ function ensureTrailingNewline(text: string): string {
   return text.endsWith("\n") ? text : `${text}\n`;
 }
 
-function buildHeader(clock: LogClock): string {
-  const created = `${clock.date}T${clock.time}${clock.offset}`;
-  return `# ${clock.date}\n> TZ: ${clock.timeZone}\n> Created: ${created}\n\n`;
+function joinFrontmatterAndBody(frontmatter: string, body: string): string {
+  const trimmedBody = body.replace(/^\n+/, "");
+  if (!trimmedBody) return frontmatter;
+  return `${frontmatter}${trimmedBody}`;
 }
 
 function formatEntryBody(message: string): string {
@@ -130,7 +284,6 @@ export async function runLog(
 
     const thresholdMinutes = parseThresholdMinutes(options.thresholdMinutes);
     const now = new Date();
-    const clock = getLocalClock(now);
 
     const baseDir = await getBaseDir();
     const rootDir = options.root
@@ -139,7 +292,10 @@ export async function runLog(
 
     await fs.mkdir(rootDir, { recursive: true });
 
-    const filePath = path.join(rootDir, `${clock.date}.md`);
+    let timeZone = getDefaultTimeZone();
+    let clock = getClockForTimeZone(now, timeZone);
+    let filePath = path.join(rootDir, `${clock.date}.md`);
+
     let content = "";
     let fileExists = false;
 
@@ -151,28 +307,69 @@ export async function runLog(
         throw err;
     }
 
-    if (!fileExists) content = buildHeader(clock);
+    let parsed = parseFrontmatter(content);
+
+    if (fileExists && parsed.hasFrontmatter && parsed.data.tz) {
+      const desiredTz = parsed.data.tz;
+      if (desiredTz !== timeZone) {
+        const altClock = safeClockForTimeZone(now, desiredTz);
+        if (altClock) {
+          timeZone = altClock.timeZone;
+          clock = altClock;
+          const altPath = path.join(rootDir, `${clock.date}.md`);
+          if (altPath !== filePath) {
+            filePath = altPath;
+            try {
+              content = await fs.readFile(filePath, "utf8");
+              fileExists = true;
+            } catch (err) {
+              if (
+                !(err instanceof Error) ||
+                !("code" in err) ||
+                err.code !== "ENOENT"
+              )
+                throw err;
+              fileExists = false;
+              content = "";
+            }
+            parsed = parseFrontmatter(content);
+          }
+        }
+      }
+    }
 
-    const lines = content.split(/\r?\n/);
-    const currentSection = `## ${clock.time.slice(0, 2)}:00`;
+    if (!fileExists) {
+      content = "";
+      parsed = { data: {}, body: "", hasFrontmatter: false };
+    }
+
+    const body = parsed.hasFrontmatter ? parsed.body : stripLegacyHeader(content);
+
+    const author = resolveAuthor();
+    const normalized = normalizeFrontmatter(parsed.data, clock, author);
+    const frontmatterText = buildFrontmatter(normalized.data);
+
+    const lines = body.split(/\r?\n/);
     const lastSection = findLastSection(lines);
     const lastEntry = findLastEntryTime(lines, clock.date);
 
-    let needsSection = false;
-    if (!lastSection || lastSection !== currentSection) needsSection = true;
-
+    let needsSection = !lastSection;
     if (!needsSection && thresholdMinutes > 0 && lastEntry) {
       const diffMs = now.getTime() - lastEntry.getTime();
       if (diffMs >= thresholdMinutes * 60_000) needsSection = true;
     }
 
-    let nextContent = ensureTrailingNewline(content);
-    if (needsSection) nextContent += `${currentSection}\n`;
+    let nextBody = ensureTrailingNewline(body);
+    if (needsSection) {
+      const sectionTitle = `## ${clock.time.slice(0, 5)}`;
+      nextBody += `${sectionTitle}\n`;
+    }
 
     const entryBody = formatEntryBody(trimmed);
-    const entryLine = `- ${clock.time}${clock.offset} ${entryBody}`;
-    nextContent += `${entryLine}\n`;
+    const entryLine = `${clock.time}${clock.offset} ${entryBody}`;
+    nextBody += `${entryLine}\n`;
 
+    const nextContent = joinFrontmatterAndBody(frontmatterText, nextBody);
     await fs.writeFile(filePath, nextContent, "utf8");
     process.stdout.write(`Logged to ${filePath}\n`);
   } catch (err) {

From 68947c7b048767f4c844f1571dfeb66dbda3d5ab Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:02:52 +0100
Subject: [PATCH 10/26] Adjust SimpleLog entry formatting

---
 docs/SIMPLELOG_SPEC.md  | 13 +++++++++----
 docs/logs/2026-02-04.md |  5 ++++-
 src/cli/log.ts          | 42 +++++++++++++++++++++++++++++------------
 3 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index 1fa6b8f..91f5ec4 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -72,7 +72,7 @@ Rules:
 
 ## 5) Entry format (appendable, human-readable, parseable)
 
-Each entry is a single line starting with a local-time timestamp **including timezone offset**.
+Each entry is a block of text separated by at least one blank line. The first line of the block MUST start with a local-time timestamp **including timezone offset**.
 
 Required entry prefix:
 
@@ -93,14 +93,17 @@ Examples:
 
 ```md
 09:13+01:00 Standup notes #team
+
 09:14:10+01:00 [WARN] API latency spike service=orders p95_ms=840
+
 14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
 ```
 
 Multiline entries:
 
-- Continuation lines MUST be indented by two spaces (or more) to remain associated with the entry above.
-- CLI implementations SHOULD indent newline characters from user input by two spaces so multiline entries remain valid.
+- Continuation lines are allowed and are stored as-is.
+- Continuation lines SHOULD NOT start with a timestamp prefix, because that denotes a new entry.
+- CLI implementations SHOULD NOT alter indentation; they only ensure a blank line separates entries.
 
 Example:
 
@@ -139,7 +142,8 @@ When the CLI writes an entry:
    - no section exists yet, or
    - the last entry is older than the threshold (for example, 5 minutes).
      The new section title MUST be the current local time in `HH:MM` format.
-5. Append the new entry as the last line in the current section, indenting multiline input by two spaces.
+5. Ensure there is a blank line between the last existing line and the new entry.
+6. Append the new entry block using the exact input text (no indentation changes), with the timestamp prefix added to the first line.
 
 This guarantees the tool only appends (no in-file insertion) while keeping session grouping.
 
@@ -159,6 +163,7 @@ created: 2025-12-01T00:00:00+01:00
 ## 09:13
 
 09:13:42+01:00 Checked alerts #ops
+
 09:14:10+01:00 [WARN] Elevated error rate service=api code=502
 notes="started after deploy"
 
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index f9e38c9..a3c8b9d 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -9,9 +9,12 @@ created: 2026-02-04T20:35:26+01:00
 ## 20:35
 
 20:35:26+01:00 Implemented simpledoc log command with auto timezone/date and thresholded sections; writing this entry to document the work.
+
 20:39:32+01:00 Added multiline support to simpledoc log.
 
 - CLI now accepts --stdin and preserves newline content with proper indentation.
 - Spec updated to mention CLI indentation for multiline input.
-  20:43:06+01:00 Auto-read stdin for simpledoc log when piped, matching Unix utility expectations.
+
+20:43:06+01:00 Auto-read stdin for simpledoc log when piped, matching Unix utility expectations.
+
 - Kept --stdin for explicit use.
diff --git a/src/cli/log.ts b/src/cli/log.ts
index 3a65c59..a4ad04e 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -258,20 +258,32 @@ function ensureTrailingNewline(text: string): string {
   return text.endsWith("\n") ? text : `${text}\n`;
 }
 
+function ensureBlankLine(text: string): string {
+  if (text === "") return "";
+  if (text.endsWith("\n\n")) return text;
+  if (text.endsWith("\n")) return `${text}\n`;
+  return `${text}\n\n`;
+}
+
 function joinFrontmatterAndBody(frontmatter: string, body: string): string {
   const trimmedBody = body.replace(/^\n+/, "");
   if (!trimmedBody) return frontmatter;
   return `${frontmatter}${trimmedBody}`;
 }
 
-function formatEntryBody(message: string): string {
-  const normalized = message.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+function normalizeEntryBody(message: string): string {
+  const normalized = message.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const withoutLeadingBlank = normalized.replace(/^\n+/, "");
+  return withoutLeadingBlank.replace(/\n+$/, "");
+}
+
+function buildEntryText(clock: LogClock, message: string): string {
+  const normalized = normalizeEntryBody(message);
   const lines = normalized.split("\n");
-  if (lines.length === 0) return "";
   const [first, ...rest] = lines;
-  if (rest.length === 0) return first ?? "";
-  const indented = rest.map((line) => `  ${line}`);
-  return [first ?? "", ...indented].join("\n");
+  const head = `${clock.time}${clock.offset} ${first ?? ""}`;
+  if (rest.length === 0) return head;
+  return `${head}\n${rest.join("\n")}`;
 }
 
 export async function runLog(
@@ -279,8 +291,11 @@ export async function runLog(
   options: LogOptions,
 ): Promise<void> {
   try {
-    const trimmed = message.trim();
-    if (!trimmed) throw new Error("Log entry message is required.");
+    const normalizedMessage = message
+      .replace(/\r\n/g, "\n")
+      .replace(/\r/g, "\n");
+    if (!normalizedMessage.trim())
+      throw new Error("Log entry message is required.");
 
     const thresholdMinutes = parseThresholdMinutes(options.thresholdMinutes);
     const now = new Date();
@@ -343,7 +358,9 @@ export async function runLog(
       parsed = { data: {}, body: "", hasFrontmatter: false };
     }
 
-    const body = parsed.hasFrontmatter ? parsed.body : stripLegacyHeader(content);
+    const body = parsed.hasFrontmatter
+      ? parsed.body
+      : stripLegacyHeader(content);
 
     const author = resolveAuthor();
     const normalized = normalizeFrontmatter(parsed.data, clock, author);
@@ -360,14 +377,15 @@ export async function runLog(
     }
 
     let nextBody = ensureTrailingNewline(body);
+    if (nextBody.trim() !== "") nextBody = ensureBlankLine(nextBody);
     if (needsSection) {
       const sectionTitle = `## ${clock.time.slice(0, 5)}`;
       nextBody += `${sectionTitle}\n`;
+      nextBody = ensureBlankLine(nextBody);
     }
 
-    const entryBody = formatEntryBody(trimmed);
-    const entryLine = `${clock.time}${clock.offset} ${entryBody}`;
-    nextBody += `${entryLine}\n`;
+    const entryText = buildEntryText(clock, normalizedMessage);
+    nextBody += `${entryText}\n`;
 
     const nextContent = joinFrontmatterAndBody(frontmatterText, nextBody);
     await fs.writeFile(filePath, nextContent, "utf8");

From 718eddde1d9989d7ef653f0255ee7d07975cee55 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:07:26 +0100
Subject: [PATCH 11/26] Remove auto timestamps from SimpleLog

---
 docs/SIMPLELOG_SPEC.md  | 39 +++++++++++++++------------------------
 docs/logs/2026-02-04.md |  9 ++++++---
 src/cli/log.ts          | 30 +++++++++++++++++++-----------
 3 files changed, 40 insertions(+), 38 deletions(-)

diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index 91f5ec4..d25934f 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -72,56 +72,47 @@ Rules:
 
 ## 5) Entry format (appendable, human-readable, parseable)
 
-Each entry is a block of text separated by at least one blank line. The first line of the block MUST start with a local-time timestamp **including timezone offset**.
-
-Required entry prefix:
-
-- `<TIME><OFFSET> `
-
-Where:
-
-- `<TIME>` is `HH:MM` or `HH:MM:SS`
-- `<OFFSET>` is `Z` or `+HH:MM` or `-HH:MM` (e.g., `+01:00`, `-05:00`)
+Each entry is a block of text separated by at least one blank line. The entry body is freeform; the only reserved syntax is the session section headings.
 
 Recommended entry body conventions (all optional):
 
 - Severity token: `[INFO]`, `[WARN]`, `[ERROR]`, etc.
 - Tags: `#tag` tokens
 - Key-values: `key=value` tokens (values may be quoted)
+- Optional timestamp prefix if you want exact times per entry, e.g. `09:14:10+01:00 ...`.
 
 Examples:
 
 ```md
-09:13+01:00 Standup notes #team
+Standup notes #team
 
-09:14:10+01:00 [WARN] API latency spike service=orders p95_ms=840
+[WARN] API latency spike service=orders p95_ms=840
 
-14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
+09:14:10+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
 ```
 
 Multiline entries:
 
 - Continuation lines are allowed and are stored as-is.
-- Continuation lines SHOULD NOT start with a timestamp prefix, because that denotes a new entry.
 - CLI implementations SHOULD NOT alter indentation; they only ensure a blank line separates entries.
 
 Example:
 
 ```md
-14:27:05+01:00 Incident review #ops
+Incident review #ops
 
 - suspected cause: cache stampede
 - mitigation: rate-limit + warmup
 ```
 
-## 6) Deriving a full timestamp
+## 6) Optional full timestamp derivation
 
-Given:
+If an entry begins with a timestamp prefix, you can derive a full timestamp by combining it with the file date:
 
 - file date `YYYY-MM-DD`
 - entry prefix `HH:MM[:SS]+HH:MM` or `HH:MM[:SS]-HH:MM`
 
-The full timestamp is:
+Full timestamp:
 
 - `YYYY-MM-DDTHH:MM[:SS]+HH:MM` or `YYYY-MM-DDTHH:MM[:SS]-HH:MM`
 
@@ -143,7 +134,7 @@ When the CLI writes an entry:
    - the last entry is older than the threshold (for example, 5 minutes).
      The new section title MUST be the current local time in `HH:MM` format.
 5. Ensure there is a blank line between the last existing line and the new entry.
-6. Append the new entry block using the exact input text (no indentation changes), with the timestamp prefix added to the first line.
+6. Append the new entry block using the exact input text (no indentation changes).
 
 This guarantees the tool only appends (no in-file insertion) while keeping session grouping.
 
@@ -162,18 +153,18 @@ created: 2025-12-01T00:00:00+01:00
 
 ## 09:13
 
-09:13:42+01:00 Checked alerts #ops
+Checked alerts #ops
 
-09:14:10+01:00 [WARN] Elevated error rate service=api code=502
+[WARN] Elevated error rate service=api code=502
 notes="started after deploy"
 
 ## 14:03
 
-14:03:22+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
+Deployed v1.8.2 #deploy ticket=ABC-123
 
 ## 14:27
 
-14:27:05+01:00 Incident review #ops
+Incident review #ops
 
 - suspected cause: cache stampede
 - mitigation: rate-limit + warmup
@@ -184,4 +175,4 @@ notes="started after deploy"
 If you need multiple timezones in one file (rare, but possible):
 
 - Keep the frontmatter `tz` as the default.
-- Allow an optional zone ID after the offset, e.g. `10:00:00+01:00 Europe/Berlin ...`.
+- Allow an optional zone ID after the offset if you include a timestamp prefix, e.g. `10:00:00+01:00 Europe/Berlin ...`.
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index a3c8b9d..2113188 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,17 +4,20 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
+updated: 2026-02-04T20:49:38+01:00
 ---
 
 ## 20:35
 
-20:35:26+01:00 Implemented simpledoc log command with auto timezone/date and thresholded sections; writing this entry to document the work.
+Implemented simpledoc log command with auto timezone/date and thresholded sections; writing this entry to document the work.
 
-20:39:32+01:00 Added multiline support to simpledoc log.
+Added multiline support to simpledoc log.
 
 - CLI now accepts --stdin and preserves newline content with proper indentation.
 - Spec updated to mention CLI indentation for multiline input.
 
-20:43:06+01:00 Auto-read stdin for simpledoc log when piped, matching Unix utility expectations.
+Auto-read stdin for simpledoc log when piped, matching Unix utility expectations.
 
 - Kept --stdin for explicit use.
+
+Updated SimpleLog to preserve raw input and insert a blank line before new entries, without indentation changes.
diff --git a/src/cli/log.ts b/src/cli/log.ts
index a4ad04e..c3c2cf9 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -278,12 +278,14 @@ function normalizeEntryBody(message: string): string {
 }
 
 function buildEntryText(clock: LogClock, message: string): string {
-  const normalized = normalizeEntryBody(message);
-  const lines = normalized.split("\n");
-  const [first, ...rest] = lines;
-  const head = `${clock.time}${clock.offset} ${first ?? ""}`;
-  if (rest.length === 0) return head;
-  return `${head}\n${rest.join("\n")}`;
+  return normalizeEntryBody(message);
+}
+
+function parseIsoTimestamp(value: string | undefined): Date | null {
+  if (!value) return null;
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return null;
+  return parsed;
 }
 
 export async function runLog(
@@ -364,13 +366,14 @@ export async function runLog(
 
     const author = resolveAuthor();
     const normalized = normalizeFrontmatter(parsed.data, clock, author);
-    const frontmatterText = buildFrontmatter(normalized.data);
-
     const lines = body.split(/\r?\n/);
     const lastSection = findLastSection(lines);
-    const lastEntry = findLastEntryTime(lines, clock.date);
+    const lastEntry =
+      parseIsoTimestamp(parsed.data.updated) ??
+      parseIsoTimestamp(parsed.data.created) ??
+      findLastEntryTime(lines, clock.date);
 
-    let needsSection = !lastSection;
+    let needsSection = !lastSection || !lastEntry;
     if (!needsSection && thresholdMinutes > 0 && lastEntry) {
       const diffMs = now.getTime() - lastEntry.getTime();
       if (diffMs >= thresholdMinutes * 60_000) needsSection = true;
@@ -387,7 +390,12 @@ export async function runLog(
     const entryText = buildEntryText(clock, normalizedMessage);
     nextBody += `${entryText}\n`;
 
-    const nextContent = joinFrontmatterAndBody(frontmatterText, nextBody);
+    const updated = `${clock.date}T${clock.time}${clock.offset}`;
+    const updatedFrontmatter = buildFrontmatter({
+      ...normalized.data,
+      updated,
+    });
+    const nextContent = joinFrontmatterAndBody(updatedFrontmatter, nextBody);
     await fs.writeFile(filePath, nextContent, "utf8");
     process.stdout.write(`Logged to ${filePath}\n`);
   } catch (err) {

From 92d7b25ca604ea5c7ad14b3d5863d5127e6069e1 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:09:56 +0100
Subject: [PATCH 12/26] Log latest SimpleLog CLI tests

---
 docs/logs/2026-02-04.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 2113188..78a9b38 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T20:49:38+01:00
+updated: 2026-02-04T21:09:37+01:00
 ---
 
 ## 20:35
@@ -21,3 +21,12 @@ Auto-read stdin for simpledoc log when piped, matching Unix utility expectations
 - Kept --stdin for explicit use.
 
 Updated SimpleLog to preserve raw input and insert a blank line before new entries, without indentation changes.
+
+## 21:08
+
+Test run after removing auto timestamps and keeping blank-line separation.
+
+Multiline test entry.
+
+- line two
+- line three

From 743e81eecd7047d83735c5f33ae7df4fb5503147 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:11:11 +0100
Subject: [PATCH 13/26] Mention SimpleLog spec in README

---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index d267f56..d787a1a 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,8 @@ SimpleDoc defines two types of files:
 1. **Date-prefixed files**: SHOULD be used for most documents, e.g. `docs/2025-12-22-an-awesome-doc.md`.
 2. **Capitalized files**: SHOULD be used for general documents that are not tied to a specific time, e.g. `README.md`.
 
+SimpleDoc also includes optional subspecs for specialized document types, such as the SimpleLog daily log format in `docs/SIMPLELOG_SPEC.md`.
+
 ### 1. Date-prefixed files
 
 - Date-prefixed Markdown files SHOULD be used for most documents that are tied to a specific time.

From 69bf935ae3fe3a7393284b5c999949994fd6dad8 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:13:55 +0100
Subject: [PATCH 14/26] Document SimpleLog usage in skill

---
 skills/simpledoc/SKILL.md | 49 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/skills/simpledoc/SKILL.md b/skills/simpledoc/SKILL.md
index 49fe001..da8fa5e 100644
--- a/skills/simpledoc/SKILL.md
+++ b/skills/simpledoc/SKILL.md
@@ -83,6 +83,55 @@ SimpleDoc Guidelines:
 - Choose a concise, action-oriented `title`.
 - Populate `tags` when it improves discoverability; omit the line if not needed.
 
+## Daily Logs (SimpleLog)
+
+Use SimpleLog for daily logs. The spec lives at `docs/SIMPLELOG_SPEC.md`.
+
+### Where logs live
+
+- Default location: `docs/logs/YYYY-MM-DD.md`.
+- The CLI writes to `<repo-root>/docs/logs/` by default when inside a git repo.
+
+### Create a daily log entry (recommended)
+
+Use the CLI to create the file and append entries:
+
+```bash
+simpledoc log "Entry text here"
+```
+
+Notes:
+
+- The CLI creates the daily log file if missing, including required frontmatter.
+- It adds a new session section only when the threshold is exceeded (default 5 minutes).
+- It preserves the text you type and inserts a blank line before each new entry.
+
+### Multiline entries
+
+Pipe or heredoc input (stdin) for multiline entries:
+
+```bash
+cat <<'EOF' | simpledoc log
+Multiline entry.
+- line two
+- line three
+EOF
+```
+
+You can also use `--stdin` explicitly:
+
+```bash
+simpledoc log --stdin <<'EOF'
+Another multiline entry.
+EOF
+```
+
+### Manual edits (if needed)
+
+- Keep the YAML frontmatter intact (`title`, `author`, `date`, `tz`, `created`, optional `updated`).
+- Ensure a blank line separates entries.
+- Session sections must be `## HH:MM` (local time of the first entry in that section).
+
 ## Final Checks Before Submitting
 
 - [ ] Filename follows the `YYYY-MM-DD-…` pattern (date uses dashes) and lives in the correct directory.

From bb05fe10ecbd079cd403a8b3432df747c90e5814 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:16:05 +0100
Subject: [PATCH 15/26] Add agent logging guidance to skill

---
 docs/logs/2026-02-04.md   | 12 +++++++++++-
 skills/simpledoc/SKILL.md | 10 ++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 78a9b38..b4ebe7f 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:09:37+01:00
+updated: 2026-02-04T21:15:56+01:00
 ---
 
 ## 20:35
@@ -30,3 +30,13 @@ Multiline test entry.
 
 - line two
 - line three
+
+## 21:14
+
+Summarized today’s SimpleLog changes and tests.
+
+- Updated spec to drop auto timestamps, require frontmatter, and use threshold-based session sections.
+- Adjusted CLI to preserve raw input, insert blank lines, and update frontmatter timestamps.
+- Logged multiline and stdin behaviors; updated README and skill docs.
+
+Updated SimpleDoc skill to instruct agents to log noteworthy actions and discoveries.
diff --git a/skills/simpledoc/SKILL.md b/skills/simpledoc/SKILL.md
index da8fa5e..d5e2d78 100644
--- a/skills/simpledoc/SKILL.md
+++ b/skills/simpledoc/SKILL.md
@@ -132,6 +132,16 @@ EOF
 - Ensure a blank line separates entries.
 - Session sections must be `## HH:MM` (local time of the first entry in that section).
 
+### Ongoing logging (agent behavior)
+
+Once this skill is active in a repo, the agent SHOULD add a SimpleLog entry for anything noteworthy, such as:
+
+- A significant change, decision, or discovery.
+- A non-obvious tradeoff or assumption.
+- A failure, error, or workaround.
+
+Log the entry after completing the action or realizing the insight.
+
 ## Final Checks Before Submitting
 
 - [ ] Filename follows the `YYYY-MM-DD-…` pattern (date uses dashes) and lives in the correct directory.

From 79b632ac5155aa62097904567079dc50c78f9e58 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:16:49 +0100
Subject: [PATCH 16/26] Log ongoing progress in skill guidance

---
 docs/logs/2026-02-04.md   |  4 +++-
 skills/simpledoc/SKILL.md | 11 ++++++-----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index b4ebe7f..64405ea 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:15:56+01:00
+updated: 2026-02-04T21:16:43+01:00
 ---
 
 ## 20:35
@@ -40,3 +40,5 @@ Summarized today’s SimpleLog changes and tests.
 - Logged multiline and stdin behaviors; updated README and skill docs.
 
 Updated SimpleDoc skill to instruct agents to log noteworthy actions and discoveries.
+
+Updated SimpleDoc skill to log ongoing progress, not just significant events.
diff --git a/skills/simpledoc/SKILL.md b/skills/simpledoc/SKILL.md
index d5e2d78..2d54fef 100644
--- a/skills/simpledoc/SKILL.md
+++ b/skills/simpledoc/SKILL.md
@@ -134,13 +134,14 @@ EOF
 
 ### Ongoing logging (agent behavior)
 
-Once this skill is active in a repo, the agent SHOULD add a SimpleLog entry for anything noteworthy, such as:
+Once this skill is active in a repo, the agent SHOULD log ongoing progress as it goes (not just significant events). This includes small but real steps, such as:
 
-- A significant change, decision, or discovery.
-- A non-obvious tradeoff or assumption.
-- A failure, error, or workaround.
+- Implementing a change or refactor.
+- Running tests or commands.
+- Updating docs or specs.
+- Learning or clarifying behavior.
 
-Log the entry after completing the action or realizing the insight.
+Log each entry after completing the step.
 
 ## Final Checks Before Submitting
 

From 7a57edb517f98a140ef45fc6259578243bce535d Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:17:45 +0100
Subject: [PATCH 17/26] Broaden skill logging guidance

---
 docs/logs/2026-02-04.md   |  4 +++-
 skills/simpledoc/SKILL.md | 11 +++++------
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 64405ea..a5f7cf4 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:16:43+01:00
+updated: 2026-02-04T21:17:35+01:00
 ---
 
 ## 20:35
@@ -42,3 +42,5 @@ Summarized today’s SimpleLog changes and tests.
 Updated SimpleDoc skill to instruct agents to log noteworthy actions and discoveries.
 
 Updated SimpleDoc skill to log ongoing progress, not just significant events.
+
+Expanded SimpleDoc skill logging guidance to cover anything worth noting (significant events and ongoing progress).
diff --git a/skills/simpledoc/SKILL.md b/skills/simpledoc/SKILL.md
index 2d54fef..4e057f8 100644
--- a/skills/simpledoc/SKILL.md
+++ b/skills/simpledoc/SKILL.md
@@ -134,14 +134,13 @@ EOF
 
 ### Ongoing logging (agent behavior)
 
-Once this skill is active in a repo, the agent SHOULD log ongoing progress as it goes (not just significant events). This includes small but real steps, such as:
+Once this skill is active in a repo, the agent SHOULD log anything worth noting as it goes. This includes:
 
-- Implementing a change or refactor.
-- Running tests or commands.
-- Updating docs or specs.
-- Learning or clarifying behavior.
+- Significant changes, decisions, discoveries, tradeoffs, and assumptions.
+- Ongoing progress and small but real steps (changes, commands, tests, doc updates).
+- Errors, failures, workarounds, and clarifications.
 
-Log each entry after completing the step.
+Log each entry after completing the step or realizing the insight.
 
 ## Final Checks Before Submitting
 

From 56cc0e62d551006024d6698c2801f93e79d6d892 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:21:30 +0100
Subject: [PATCH 18/26] Document SimpleDoc config files

---
 .gitignore                    |  1 +
 README.md                     |  1 +
 docs/SIMPLEDOC_CONFIG_SPEC.md | 85 +++++++++++++++++++++++++++++++++++
 docs/SIMPLELOG_SPEC.md        |  2 +-
 docs/logs/2026-02-04.md       |  7 ++-
 skills/simpledoc/SKILL.md     |  1 +
 6 files changed, 95 insertions(+), 2 deletions(-)
 create mode 100644 docs/SIMPLEDOC_CONFIG_SPEC.md

diff --git a/.gitignore b/.gitignore
index 854b00f..2e2d042 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@
 node_modules
 dist
 dist-test
+.simpledoc.local.json
diff --git a/README.md b/README.md
index d787a1a..485a5ff 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ SimpleDoc defines two types of files:
 2. **Capitalized files**: SHOULD be used for general documents that are not tied to a specific time, e.g. `README.md`.
 
 SimpleDoc also includes optional subspecs for specialized document types, such as the SimpleLog daily log format in `docs/SIMPLELOG_SPEC.md`.
+Configuration for tooling can be shared in `simpledoc.json` and overridden per-user in `.simpledoc.local.json` (see `docs/SIMPLEDOC_CONFIG_SPEC.md`).
 
 ### 1. Date-prefixed files
 
diff --git a/docs/SIMPLEDOC_CONFIG_SPEC.md b/docs/SIMPLEDOC_CONFIG_SPEC.md
new file mode 100644
index 0000000..5383392
--- /dev/null
+++ b/docs/SIMPLEDOC_CONFIG_SPEC.md
@@ -0,0 +1,85 @@
+# SimpleDoc Config
+
+> Repository and local configuration for SimpleDoc tools
+
+## 1) Config files
+
+SimpleDoc tooling MAY read two JSON config files at the repo root:
+
+- `simpledoc.json` (committed, shared defaults)
+- `.simpledoc.local.json` (uncommitted, per-user overrides)
+
+Both files are optional.
+
+## 2) File format
+
+- MUST be valid JSON.
+- MUST be UTF-8.
+- MUST use LF (`\n`) newlines.
+
+## 3) Precedence
+
+Configuration values are resolved in this order (highest wins):
+
+1. CLI flags
+2. `.simpledoc.local.json`
+3. `simpledoc.json`
+4. Tool defaults
+
+## 4) Schema
+
+Top-level object. Current keys:
+
+```json
+{
+  "simplelog": {
+    "root": "docs/logs",
+    "thresholdMinutes": 5
+  }
+}
+```
+
+### simplelog.root
+
+- **Type:** string
+- **Meaning:** Root directory for SimpleLog daily files.
+- **Resolution:** If relative, it is resolved from the repo root.
+- **Recommendation:** Use a shared path in `simpledoc.json` (e.g. `docs/logs`) and a per-user path in `.simpledoc.local.json` when needed (e.g. `docs/logs/_local/<name>`).
+
+### simplelog.thresholdMinutes
+
+- **Type:** number
+- **Meaning:** Default threshold (in minutes) for starting a new session section.
+- **Default:** 5
+- **Notes:** CLI flags should override this when provided.
+
+## 5) Usage examples
+
+### Shared default (committed)
+
+`simpledoc.json`
+
+```json
+{
+  "simplelog": {
+    "root": "docs/logs"
+  }
+}
+```
+
+### Local override (uncommitted)
+
+`.simpledoc.local.json`
+
+```json
+{
+  "simplelog": {
+    "root": "docs/logs/_local/alice",
+    "thresholdMinutes": 2
+  }
+}
+```
+
+## 6) Git ignore
+
+Teams SHOULD add `.simpledoc.local.json` to `.gitignore` to prevent accidental commits.
diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index d25934f..deebc5a 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -124,7 +124,7 @@ Example:
 
 ## 7) CLI append behavior (normative)
 
-When the CLI writes an entry:
+When the CLI writes an entry (config is resolved via `simpledoc.json` / `.simpledoc.local.json` if present; see `docs/SIMPLEDOC_CONFIG_SPEC.md`):
 
 1. Determine "now" in the primary timezone from frontmatter (or CLI config).
 2. Select file by the local date in that timezone: `YYYY-MM-DD.md`.
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index a5f7cf4..17cce5c 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:17:35+01:00
+updated: 2026-02-04T21:21:16+01:00
 ---
 
 ## 20:35
@@ -44,3 +44,8 @@ Updated SimpleDoc skill to instruct agents to log noteworthy actions and discove
 Updated SimpleDoc skill to log ongoing progress, not just significant events.
 
 Expanded SimpleDoc skill logging guidance to cover anything worth noting (significant events and ongoing progress).
+
+Added config spec for simpledoc.json and .simpledoc.local.json with precedence and schema details.
+
+- Documented usage in README, SimpleLog spec, and SimpleDoc skill.
+- Added .simpledoc.local.json to .gitignore.
diff --git a/skills/simpledoc/SKILL.md b/skills/simpledoc/SKILL.md
index 4e057f8..5cc10e7 100644
--- a/skills/simpledoc/SKILL.md
+++ b/skills/simpledoc/SKILL.md
@@ -91,6 +91,7 @@ Use SimpleLog for daily logs. The spec lives at `docs/SIMPLELOG_SPEC.md`.
 
 - Default location: `docs/logs/YYYY-MM-DD.md`.
 - The CLI writes to `<repo-root>/docs/logs/` by default when inside a git repo.
+- You can set a shared default in `simpledoc.json` and override locally in `.simpledoc.local.json` (see `docs/SIMPLEDOC_CONFIG_SPEC.md`).
 
 ### Create a daily log entry (recommended)
 

From 0b6deee357682059486f1c64de5e6b069bf809d1 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:26:06 +0100
Subject: [PATCH 19/26] Expand SimpleDoc config spec

---
 docs/SIMPLEDOC_CONFIG_SPEC.md | 73 ++++++++++++++++++++++++++++++++++-
 docs/logs/2026-02-04.md       |  4 +-
 2 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/docs/SIMPLEDOC_CONFIG_SPEC.md b/docs/SIMPLEDOC_CONFIG_SPEC.md
index 5383392..b4af334 100644
--- a/docs/SIMPLEDOC_CONFIG_SPEC.md
+++ b/docs/SIMPLEDOC_CONFIG_SPEC.md
@@ -32,13 +32,54 @@ Top-level object. Current keys:
 
 ```json
 {
+  "docs": {
+    "root": "docs"
+  },
+  "frontmatter": {
+    "defaults": {
+      "author": "Jane Doe <jane@example.com>",
+      "tags": ["docs", "simpledoc"],
+      "titlePrefix": "Daily Log"
+    }
+  },
+  "check": {
+    "ignore": ["docs/generated/**", "docs/_drafts/**"]
+  },
   "simplelog": {
     "root": "docs/logs",
-    "thresholdMinutes": 5
+    "thresholdMinutes": 5,
+    "timezone": "Europe/Berlin"
   }
 }
 ```
 
+### docs.root
+
+- **Type:** string
+- **Meaning:** Root directory for SimpleDoc-managed documentation.
+- **Resolution:** If relative, it is resolved from the repo root.
+- **Default:** `docs`
+- **Notes:** Tools like `simpledoc check` and `simpledoc migrate` SHOULD treat this as the documentation root.
+
+### frontmatter.defaults
+
+- **Type:** object
+- **Meaning:** Default frontmatter values to use when a tool needs to create or insert frontmatter.
+- **Notes:** These values SHOULD only fill missing fields and MUST NOT overwrite existing frontmatter.
+
+Supported keys:
+
+- `author` (string): Default `Name <email>` to use.
+- `tags` (string array): Default tags to add (optional).
+- `titlePrefix` (string): Prefix used when generating titles (optional).
+
+### check.ignore
+
+- **Type:** array of strings
+- **Meaning:** Glob-like patterns to ignore when scanning for violations in `simpledoc check` (and optionally other scans).
+- **Resolution:** Patterns are matched relative to the repo root.
+- **Notes:** Ignored paths SHOULD be skipped entirely during scans.
+
 ### simplelog.root
 
 - **Type:** string
@@ -53,6 +94,13 @@ Top-level object. Current keys:
 - **Default:** 5
 - **Notes:** CLI flags should override this when provided.
 
+### simplelog.timezone
+
+- **Type:** string
+- **Meaning:** IANA timezone ID to use when creating new SimpleLog files and sections.
+- **Default:** System timezone (or `UTC` if unavailable).
+- **Notes:** If a SimpleLog file exists with a `tz` frontmatter value, that value SHOULD take precedence for that file.
+
 ## 5) Usage examples
 
 ### Shared default (committed)
@@ -61,6 +109,18 @@ Top-level object. Current keys:
 
 ```json
 {
+  "docs": {
+    "root": "docs"
+  },
+  "frontmatter": {
+    "defaults": {
+      "author": "Jane Doe <jane@example.com>",
+      "tags": ["docs", "simpledoc"]
+    }
+  },
+  "check": {
+    "ignore": ["docs/generated/**"]
+  },
   "simplelog": {
     "root": "docs/logs"
   }
@@ -73,9 +133,18 @@ Top-level object. Current keys:
 
 ```json
 {
+  "docs": {
+    "root": "docs"
+  },
+  "frontmatter": {
+    "defaults": {
+      "author": "Alice Example <alice@example.com>"
+    }
+  },
   "simplelog": {
     "root": "docs/logs/_local/alice",
-    "thresholdMinutes": 2
+    "thresholdMinutes": 2,
+    "timezone": "Europe/Berlin"
   }
 }
 ```
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 17cce5c..c878c18 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:21:16+01:00
+updated: 2026-02-04T21:25:51+01:00
 ---
 
 ## 20:35
@@ -49,3 +49,5 @@ Added config spec for simpledoc.json and .simpledoc.local.json with precedence a
 
 - Documented usage in README, SimpleLog spec, and SimpleDoc skill.
 - Added .simpledoc.local.json to .gitignore.
+
+Expanded config spec with docs.root, frontmatter.defaults, check.ignore, and simplelog.timezone.

From d9aeb4d87448d1979cf98c1cd0400b3da208b624 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 21:44:44 +0100
Subject: [PATCH 20/26] Add config support for SimpleDoc tools

---
 docs/SIMPLEDOC_CONFIG_SPEC.md           |   1 +
 docs/logs/2026-02-04.md                 |  10 +-
 src/cli/check.ts                        |   9 +-
 src/cli/index.ts                        |  14 +-
 src/cli/install.ts                      |   5 +
 src/cli/log.ts                          |  70 +++++---
 src/cli/migrate.ts                      |  32 +++-
 src/cli/steps/naming-lowercase.ts       |   6 +-
 src/cli/steps/root-move.ts              |  21 ++-
 src/config.ts                           | 215 ++++++++++++++++++++++++
 src/doc-classifier.ts                   |  18 +-
 src/migrator.ts                         | 120 +++++++++++--
 test/integration/config.test.ts         |  62 +++++++
 test/integration/migrator.apply.test.ts |  27 +++
 test/integration/migrator.plan.test.ts  |  44 +++++
 15 files changed, 592 insertions(+), 62 deletions(-)
 create mode 100644 src/config.ts
 create mode 100644 test/integration/config.test.ts

diff --git a/docs/SIMPLEDOC_CONFIG_SPEC.md b/docs/SIMPLEDOC_CONFIG_SPEC.md
index b4af334..723da8f 100644
--- a/docs/SIMPLEDOC_CONFIG_SPEC.md
+++ b/docs/SIMPLEDOC_CONFIG_SPEC.md
@@ -85,6 +85,7 @@ Supported keys:
 - **Type:** string
 - **Meaning:** Root directory for SimpleLog daily files.
 - **Resolution:** If relative, it is resolved from the repo root.
+- **Default:** `${docs.root}/logs` (falls back to `docs/logs` if `docs.root` is unset).
 - **Recommendation:** Use a shared path in `simpledoc.json` (e.g. `docs/logs`) and a per-user path in `.simpledoc.local.json` when needed (e.g. `docs/logs/_local/<name>`).
 
 ### simplelog.thresholdMinutes
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index c878c18..60521a3 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:25:51+01:00
+updated: 2026-02-04T21:44:25+01:00
 ---
 
 ## 20:35
@@ -51,3 +51,11 @@ Added config spec for simpledoc.json and .simpledoc.local.json with precedence a
 - Added .simpledoc.local.json to .gitignore.
 
 Expanded config spec with docs.root, frontmatter.defaults, check.ignore, and simplelog.timezone.
+
+## 21:44
+
+Implemented config loading (simpledoc.json + .simpledoc.local.json) with precedence and defaults.
+
+- Wired docs.root, frontmatter.defaults, check.ignore, and simplelog.\* into CLI + migrator logic.
+- Added config tests plus docsRoot/ignore/frontmatter default coverage.
+- Ran npm test (all passing).
diff --git a/src/cli/check.ts b/src/cli/check.ts
index 6903a8d..088616d 100644
--- a/src/cli/check.ts
+++ b/src/cli/check.ts
@@ -7,6 +7,7 @@ import {
   type ReferenceUpdateAction,
   type RenameAction,
 } from "../migrator.js";
+import { loadConfig } from "../config.js";
 import {
   MAX_STEP_FILE_PREVIEW_LINES,
   createScanProgressBarReporter,
@@ -20,10 +21,16 @@ function getErrorMessage(err: unknown): string {
 
 export async function runCheck(): Promise<void> {
   try {
+    const config = await loadConfig(process.cwd());
     const scanProgress = createScanProgressBarReporter(
       Boolean(process.stdin.isTTY && process.stdout.isTTY),
     );
-    const plan = await planMigration({ onProgress: scanProgress });
+    const plan = await planMigration({
+      onProgress: scanProgress,
+      docsRoot: config.docsRoot,
+      ignoreGlobs: config.checkIgnore,
+      frontmatterDefaults: config.frontmatterDefaults,
+    });
 
     const renames = plan.actions.filter(
       (a): a is RenameAction => a.type === "rename",
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 5a3f616..9d3c07d 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -18,7 +18,7 @@ type InstallOptions = {
 };
 type LogOptions = {
   root?: string;
-  thresholdMinutes: string;
+  thresholdMinutes?: string;
   stdin?: boolean;
 };
 
@@ -99,17 +99,21 @@ export async function runCli(argv: string[]): Promise<void> {
 
   program
     .command("log")
-    .description("Append a SimpleLog entry (Daily Markdown Log) to docs/logs.")
+    .description(
+      "Append a SimpleLog entry (Daily Markdown Log) to the configured log root.",
+    )
     .argument("[message...]", "Entry text to append")
-    .option("--root <dir>", "Root directory for log files (default: docs/logs)")
+    .option(
+      "--root <dir>",
+      "Root directory for log files (default: config or docs/logs)",
+    )
     .option(
       "--stdin",
       "Read entry text from stdin (supports multiline). If stdin is piped, it is read automatically.",
     )
     .option(
       "--threshold-minutes <minutes>",
-      "Start a new time section if the last entry is older than this (default: 5). Use 0 to disable.",
-      "5",
+      "Start a new time section if the last entry is older than this. Use 0 to disable (default: config or 5).",
     )
     .action(async (messageParts: string[], options: LogOptions) => {
       let message = messageParts.join(" ");
diff --git a/src/cli/install.ts b/src/cli/install.ts
index d78d322..e00eefb 100644
--- a/src/cli/install.ts
+++ b/src/cli/install.ts
@@ -27,6 +27,7 @@ import {
 } from "./ui.js";
 import { runMigrate } from "./migrate.js";
 import { runInstallSteps } from "./steps/install.js";
+import { loadConfig } from "../config.js";
 
 type InstallOptions = {
   dryRun: boolean;
@@ -105,6 +106,7 @@ function printMigrationSummary(info: MigrationInfo, includePreview: boolean) {
 
 export async function runInstall(options: InstallOptions): Promise<void> {
   try {
+    const config = await loadConfig(process.cwd());
     const git = createGitClient();
     const repoRootAbs = await git.getRepoRoot(process.cwd());
     const installStatus = await getInstallationStatus(repoRootAbs);
@@ -114,6 +116,9 @@ export async function runInstall(options: InstallOptions): Promise<void> {
     const migrationPlan = await planMigration({
       cwd: repoRootAbs,
       onProgress: scanProgress,
+      docsRoot: config.docsRoot,
+      ignoreGlobs: config.checkIgnore,
+      frontmatterDefaults: config.frontmatterDefaults,
     });
     const migrationInfo = buildMigrationInfo(migrationPlan);
 
diff --git a/src/cli/log.ts b/src/cli/log.ts
index c3c2cf9..9e43b3c 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -2,11 +2,11 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 
-import { createGitClient } from "../git.js";
+import { loadConfig } from "../config.js";
 
 type LogOptions = {
   root?: string;
-  thresholdMinutes: number | string;
+  thresholdMinutes?: number | string;
 };
 
 type LogClock = {
@@ -56,15 +56,6 @@ function parseThresholdMinutes(value: number | string): number {
   throw new Error("--threshold-minutes must be a number >= 0");
 }
 
-async function getBaseDir(): Promise<string> {
-  const git = createGitClient();
-  try {
-    return await git.getRepoRoot(process.cwd());
-  } catch {
-    return process.cwd();
-  }
-}
-
 function getDefaultTimeZone(): string {
   return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
 }
@@ -162,7 +153,20 @@ function stripLegacyHeader(content: string): string {
   return lines.slice(idx).join("\n");
 }
 
-function buildFrontmatter(data: Record<string, string>): string {
+type FrontmatterValue = string | string[];
+
+function yamlQuote(value: string): string {
+  const s = String(value).replace(/\r?\n/g, " ").trim();
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function formatFrontmatterValue(value: FrontmatterValue): string {
+  if (Array.isArray(value))
+    return `[${value.map((item) => yamlQuote(item)).join(", ")}]`;
+  return value;
+}
+
+function buildFrontmatter(data: Record<string, FrontmatterValue>): string {
   const preferredOrder = [
     "title",
     "author",
@@ -177,7 +181,7 @@ function buildFrontmatter(data: Record<string, string>): string {
     .sort();
   const keys = [...preferred, ...extras];
   const lines = keys
-    .map((key) => `${key}: ${data[key]}`)
+    .map((key) => `${key}: ${formatFrontmatterValue(data[key]!)}`)
     .filter((line) => !line.endsWith(": "));
   return `---\n${lines.join("\n")}\n---\n\n`;
 }
@@ -202,12 +206,14 @@ function normalizeFrontmatter(
   data: Record<string, string>,
   clock: LogClock,
   author: string,
+  titlePrefix?: string,
 ): { data: Record<string, string>; changed: boolean } {
   const next = { ...data };
   let changed = false;
 
   if (!next.title) {
-    next.title = `Daily Log ${clock.date}`;
+    const prefix = titlePrefix?.trim();
+    next.title = prefix ? `${prefix} ${clock.date}` : `Daily Log ${clock.date}`;
     changed = true;
   }
   if (!next.author) {
@@ -277,7 +283,7 @@ function normalizeEntryBody(message: string): string {
   return withoutLeadingBlank.replace(/\n+$/, "");
 }
 
-function buildEntryText(clock: LogClock, message: string): string {
+function buildEntryText(message: string): string {
   return normalizeEntryBody(message);
 }
 
@@ -299,17 +305,21 @@ export async function runLog(
     if (!normalizedMessage.trim())
       throw new Error("Log entry message is required.");
 
-    const thresholdMinutes = parseThresholdMinutes(options.thresholdMinutes);
+    const config = await loadConfig(process.cwd());
+    const thresholdMinutes =
+      options.thresholdMinutes !== undefined
+        ? parseThresholdMinutes(options.thresholdMinutes)
+        : config.simplelog.thresholdMinutes;
     const now = new Date();
 
-    const baseDir = await getBaseDir();
+    const baseDir = config.repoRootAbs;
     const rootDir = options.root
       ? path.resolve(baseDir, options.root)
-      : path.join(baseDir, "docs", "logs");
+      : path.resolve(baseDir, config.simplelog.root);
 
     await fs.mkdir(rootDir, { recursive: true });
 
-    let timeZone = getDefaultTimeZone();
+    let timeZone = config.simplelog.timezone ?? getDefaultTimeZone();
     let clock = getClockForTimeZone(now, timeZone);
     let filePath = path.join(rootDir, `${clock.date}.md`);
 
@@ -364,8 +374,13 @@ export async function runLog(
       ? parsed.body
       : stripLegacyHeader(content);
 
-    const author = resolveAuthor();
-    const normalized = normalizeFrontmatter(parsed.data, clock, author);
+    const author = config.frontmatterDefaults.author ?? resolveAuthor();
+    const normalized = normalizeFrontmatter(
+      parsed.data,
+      clock,
+      author,
+      config.frontmatterDefaults.titlePrefix,
+    );
     const lines = body.split(/\r?\n/);
     const lastSection = findLastSection(lines);
     const lastEntry =
@@ -387,14 +402,21 @@ export async function runLog(
       nextBody = ensureBlankLine(nextBody);
     }
 
-    const entryText = buildEntryText(clock, normalizedMessage);
+    const entryText = buildEntryText(normalizedMessage);
     nextBody += `${entryText}\n`;
 
     const updated = `${clock.date}T${clock.time}${clock.offset}`;
-    const updatedFrontmatter = buildFrontmatter({
+    const updatedFrontmatterData: Record<string, FrontmatterValue> = {
       ...normalized.data,
       updated,
-    });
+    };
+    if (
+      !("tags" in updatedFrontmatterData) &&
+      config.frontmatterDefaults.tags
+    ) {
+      updatedFrontmatterData.tags = config.frontmatterDefaults.tags;
+    }
+    const updatedFrontmatter = buildFrontmatter(updatedFrontmatterData);
     const nextContent = joinFrontmatterAndBody(updatedFrontmatter, nextBody);
     await fs.writeFile(filePath, nextContent, "utf8");
     process.stdout.write(`Logged to ${filePath}\n`);
diff --git a/src/cli/migrate.ts b/src/cli/migrate.ts
index 1f6ce2c..8458e8d 100644
--- a/src/cli/migrate.ts
+++ b/src/cli/migrate.ts
@@ -42,6 +42,7 @@ import { runFrontmatterStep } from "./steps/frontmatter.js";
 import { runInstallSteps } from "./steps/install.js";
 import { detectRootMoves, runRootMoveStep } from "./steps/root-move.js";
 import { runReferenceUpdatesStep } from "./steps/references.js";
+import { loadConfig } from "../config.js";
 
 type StepPreview = {
   title: string;
@@ -59,12 +60,16 @@ type MigrateOptions = {
 function buildDefaultPreviews(opts: {
   plan: MigrationPlan;
   installActions: InstallAction[];
+  docsRoot: string;
 }): StepPreview[] {
   const renameActionsAll = opts.plan.actions.filter(
     (a): a is RenameAction => a.type === "rename",
   );
-  const rootMovesAll = detectRootMoves(renameActionsAll);
-  const lowercaseRenamesAll = detectLowercaseDocRenames(renameActionsAll);
+  const rootMovesAll = detectRootMoves(renameActionsAll, opts.docsRoot);
+  const lowercaseRenamesAll = detectLowercaseDocRenames(
+    renameActionsAll,
+    opts.docsRoot,
+  );
   const categorizedRenames = new Set<string>([
     ...rootMovesAll.map((a) => a.from),
     ...lowercaseRenamesAll.map((a) => a.from),
@@ -85,7 +90,7 @@ function buildDefaultPreviews(opts: {
 
   if (rootMovesAll.length > 0)
     defaultPreviews.push({
-      title: "Relocate root Markdown docs into `docs/` (SimpleDoc convention)",
+      title: `Relocate root Markdown docs into \`${opts.docsRoot}/\` (SimpleDoc convention)`,
       actionsText: formatActions(rootMovesAll),
       actionCount: rootMovesAll.length,
     });
@@ -172,12 +177,18 @@ function printPreviews(previews: StepPreview[]): void {
 
 export async function runMigrate(options: MigrateOptions): Promise<void> {
   try {
+    const config = await loadConfig(process.cwd());
     process.stderr.write(
       "Planning changes (this may take a while on large repos)...\n",
     );
     const hasTty = hasInteractiveTty();
     const scanProgress = createScanProgressBarReporter(hasTty);
-    const planAll = await planMigration({ onProgress: scanProgress });
+    const planAll = await planMigration({
+      onProgress: scanProgress,
+      docsRoot: config.docsRoot,
+      ignoreGlobs: config.checkIgnore,
+      frontmatterDefaults: config.frontmatterDefaults,
+    });
     const installStatus = await getInstallationStatus(planAll.repoRootAbs);
 
     const installActionsAll = await buildDefaultInstallActions(installStatus);
@@ -200,6 +211,7 @@ export async function runMigrate(options: MigrateOptions): Promise<void> {
     const defaultPreviews = buildDefaultPreviews({
       plan: planAll,
       installActions: installActionsAll,
+      docsRoot: config.docsRoot,
     });
 
     if (defaultPreviews.length === 0) {
@@ -259,8 +271,11 @@ export async function runMigrate(options: MigrateOptions): Promise<void> {
       (a): a is RenameAction => a.type === "rename",
     );
 
-    const rootMovesAll = detectRootMoves(renameActionsAll);
-    const lowercaseRenamesAll = detectLowercaseDocRenames(renameActionsAll);
+    const rootMovesAll = detectRootMoves(renameActionsAll, config.docsRoot);
+    const lowercaseRenamesAll = detectLowercaseDocRenames(
+      renameActionsAll,
+      config.docsRoot,
+    );
     const categorizedRenames = new Set<string>([
       ...rootMovesAll.map((a) => a.from),
       ...lowercaseRenamesAll.map((a) => a.from),
@@ -272,7 +287,7 @@ export async function runMigrate(options: MigrateOptions): Promise<void> {
 
     const renameCaseOverrides: Record<string, RenameCaseMode> = {};
 
-    const rootMoveSel = await runRootMoveStep(rootMovesAll);
+    const rootMoveSel = await runRootMoveStep(rootMovesAll, config.docsRoot);
     if (rootMoveSel === null) return abort("Operation cancelled.");
     const includeRootMoves = rootMoveSel.include;
     Object.assign(renameCaseOverrides, rootMoveSel.renameCaseOverrides);
@@ -323,6 +338,9 @@ export async function runMigrate(options: MigrateOptions): Promise<void> {
         forceDatePrefixPaths,
         forceUndatedPaths,
         includeCanonicalRenames: Boolean(includeCapitalizedRenames),
+        docsRoot: config.docsRoot,
+        ignoreGlobs: config.checkIgnore,
+        frontmatterDefaults: config.frontmatterDefaults,
       });
     }
 
diff --git a/src/cli/steps/naming-lowercase.ts b/src/cli/steps/naming-lowercase.ts
index 570bd63..3d6b922 100644
--- a/src/cli/steps/naming-lowercase.ts
+++ b/src/cli/steps/naming-lowercase.ts
@@ -17,11 +17,13 @@ function hasDatePrefix(baseName: string): boolean {
 
 export function detectLowercaseDocRenames(
   renameActions: RenameAction[],
+  docsRoot: string,
 ): RenameAction[] {
+  const docsPrefix = `${docsRoot.replace(/\/+$/, "")}/`;
   return renameActions.filter(
     (a) =>
-      a.from.startsWith("docs/") &&
-      a.to.startsWith("docs/") &&
+      a.from.startsWith(docsPrefix) &&
+      a.to.startsWith(docsPrefix) &&
       hasDatePrefix(path.posix.basename(a.to)),
   );
 }
diff --git a/src/cli/steps/root-move.ts b/src/cli/steps/root-move.ts
index 76d2765..26bb73c 100644
--- a/src/cli/steps/root-move.ts
+++ b/src/cli/steps/root-move.ts
@@ -11,25 +11,34 @@ function formatRenameSources(actions: RenameAction[]): string {
   return actions.map((action) => `- ${action.from}`).join("\n");
 }
 
-export function detectRootMoves(renameActions: RenameAction[]): RenameAction[] {
+export function detectRootMoves(
+  renameActions: RenameAction[],
+  docsRoot: string,
+): RenameAction[] {
+  const docsPrefix = `${docsRoot.replace(/\/+$/, "")}/`;
   return renameActions.filter(
-    (a) => !a.from.includes("/") && a.to.startsWith("docs/"),
+    (a) => !a.from.includes("/") && a.to.startsWith(docsPrefix),
   );
 }
 
-export async function runRootMoveStep(actions: RenameAction[]): Promise<{
+export async function runRootMoveStep(
+  actions: RenameAction[],
+  docsRoot: string,
+): Promise<{
   include: boolean;
   renameCaseOverrides: Record<string, RenameCaseMode>;
 } | null> {
   if (actions.length === 0) return { include: false, renameCaseOverrides: {} };
 
+  const docsRootLabel = `${docsRoot.replace(/\/+$/, "")}/`;
+
   noteWrapped(
-    `Markdown files detected in the repo root (will be moved into \`docs/\`):\n\n${limitLines(formatRenameSources(actions), MAX_STEP_FILE_PREVIEW_LINES)}`,
-    `Proposed: Relocate root Markdown docs into \`docs/\` (${actions.length})`,
+    `Markdown files detected in the repo root (will be moved into \`${docsRootLabel}\`):\n\n${limitLines(formatRenameSources(actions), MAX_STEP_FILE_PREVIEW_LINES)}`,
+    `Proposed: Relocate root Markdown docs into \`${docsRootLabel}\` (${actions.length})`,
   );
 
   const choice = await promptSelect<"yes" | "customize" | "no">(
-    `Move ${actions.length} root Markdown file${actions.length === 1 ? "" : "s"} into \`docs/\`?`,
+    `Move ${actions.length} root Markdown file${actions.length === 1 ? "" : "s"} into \`${docsRootLabel}\`?`,
     [
       { label: "Yes", value: "yes" },
       { label: "Customize", value: "customize" },
diff --git a/src/config.ts b/src/config.ts
new file mode 100644
index 0000000..3269b3b
--- /dev/null
+++ b/src/config.ts
@@ -0,0 +1,215 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { createGitClient, type GitClient } from "./git.js";
+
+type FrontmatterDefaults = {
+  author?: string;
+  tags?: string[];
+  titlePrefix?: string;
+};
+
+type SimpleLogConfig = {
+  root?: string;
+  thresholdMinutes?: number;
+  timezone?: string;
+};
+
+type DocsConfig = {
+  root?: string;
+};
+
+type CheckConfig = {
+  ignore?: string[];
+};
+
+type FrontmatterConfig = {
+  defaults?: FrontmatterDefaults;
+};
+
+export type SimpleDocConfig = {
+  docs?: DocsConfig;
+  frontmatter?: FrontmatterConfig;
+  check?: CheckConfig;
+  simplelog?: SimpleLogConfig;
+};
+
+export type ResolvedSimpleDocConfig = {
+  repoRootAbs: string;
+  docsRoot: string;
+  frontmatterDefaults: FrontmatterDefaults;
+  checkIgnore: string[];
+  simplelog: {
+    root: string;
+    thresholdMinutes: number;
+    timezone?: string;
+  };
+};
+
+const DEFAULT_DOCS_ROOT = "docs";
+const DEFAULT_SIMPLELOG_THRESHOLD_MINUTES = 5;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object") return false;
+  return Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function mergeConfig(
+  base: SimpleDocConfig,
+  override: SimpleDocConfig,
+): SimpleDocConfig {
+  const out: SimpleDocConfig = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const existing = (out as Record<string, unknown>)[key];
+    if (isPlainObject(existing) && isPlainObject(value)) {
+      (out as Record<string, unknown>)[key] = mergeConfig(
+        existing as SimpleDocConfig,
+        value as SimpleDocConfig,
+      );
+    } else {
+      (out as Record<string, unknown>)[key] = value as unknown;
+    }
+  }
+  return out;
+}
+
+async function readConfigFile(
+  absPath: string,
+): Promise<SimpleDocConfig | null> {
+  try {
+    const raw = await fs.readFile(absPath, "utf8");
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) return null;
+    const data = JSON.parse(trimmed) as SimpleDocConfig;
+    if (!isPlainObject(data))
+      throw new Error("Config must be a JSON object at the top level.");
+    return data;
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT")
+      return null;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to read config ${absPath}: ${message}`);
+  }
+}
+
+function normalizeRelPath(
+  input: string | undefined,
+  repoRootAbs: string,
+  fallback: string,
+): string {
+  const trimmed = (input ?? "").trim();
+  if (!trimmed) return fallback;
+
+  let relPath = trimmed;
+  if (path.isAbsolute(relPath)) {
+    const relative = path.relative(repoRootAbs, relPath);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+      throw new Error(`Config path must be inside repo: ${relPath}`);
+    relPath = relative;
+  }
+
+  relPath = relPath.replace(/\\/g, "/");
+  relPath = relPath.replace(/^\.\//, "");
+  relPath = relPath.replace(/\/+$/, "");
+  relPath = path.posix.normalize(relPath);
+  if (relPath === "." || relPath === "") return fallback;
+  if (relPath.startsWith("../"))
+    throw new Error(`Config path must be inside repo: ${relPath}`);
+  return relPath;
+}
+
+function normalizeTags(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value))
+    throw new Error("frontmatter.defaults.tags must be an array of strings");
+  const tags = value.map((item) => String(item)).filter((item) => item.trim());
+  return tags.length > 0 ? tags : undefined;
+}
+
+function normalizeFrontmatterDefaults(value: unknown): FrontmatterDefaults {
+  if (!isPlainObject(value)) return {};
+  const author =
+    typeof value.author === "string" && value.author.trim()
+      ? value.author.trim()
+      : undefined;
+  const titlePrefix =
+    typeof value.titlePrefix === "string" && value.titlePrefix.trim()
+      ? value.titlePrefix.trim()
+      : undefined;
+  const tags = normalizeTags(value.tags);
+  return { author, titlePrefix, tags };
+}
+
+function normalizeCheckIgnore(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value))
+    throw new Error("check.ignore must be an array of strings");
+  const patterns = value
+    .map((item) => String(item).trim())
+    .filter((item) => item.length > 0);
+  return patterns;
+}
+
+function normalizeThreshold(value: unknown): number {
+  if (value === undefined) return DEFAULT_SIMPLELOG_THRESHOLD_MINUTES;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    throw new Error("simplelog.thresholdMinutes must be a number >= 0");
+  return parsed;
+}
+
+export async function loadConfig(
+  cwd: string,
+  opts?: { git?: GitClient },
+): Promise<ResolvedSimpleDocConfig> {
+  const git = opts?.git ?? createGitClient();
+  let repoRootAbs = cwd;
+  try {
+    repoRootAbs = await git.getRepoRoot(cwd);
+  } catch {
+    repoRootAbs = cwd;
+  }
+
+  const repoConfigPath = path.join(repoRootAbs, "simpledoc.json");
+  const localConfigPath = path.join(repoRootAbs, ".simpledoc.local.json");
+
+  const repoConfig = (await readConfigFile(repoConfigPath)) ?? {};
+  const localConfig = (await readConfigFile(localConfigPath)) ?? {};
+  const merged = mergeConfig(repoConfig, localConfig);
+
+  const docsRoot = normalizeRelPath(
+    merged.docs?.root,
+    repoRootAbs,
+    DEFAULT_DOCS_ROOT,
+  );
+  const simplelogRoot = normalizeRelPath(
+    merged.simplelog?.root ?? path.posix.join(docsRoot, "logs"),
+    repoRootAbs,
+    path.posix.join(docsRoot, "logs"),
+  );
+  const thresholdMinutes = normalizeThreshold(
+    merged.simplelog?.thresholdMinutes,
+  );
+  const timezone =
+    typeof merged.simplelog?.timezone === "string" &&
+    merged.simplelog.timezone.trim()
+      ? merged.simplelog.timezone.trim()
+      : undefined;
+
+  const frontmatterDefaults = normalizeFrontmatterDefaults(
+    merged.frontmatter?.defaults,
+  );
+  const checkIgnore = normalizeCheckIgnore(merged.check?.ignore);
+
+  return {
+    repoRootAbs,
+    docsRoot,
+    frontmatterDefaults,
+    checkIgnore,
+    simplelog: {
+      root: simplelogRoot,
+      thresholdMinutes,
+      timezone,
+    },
+  };
+}
diff --git a/src/doc-classifier.ts b/src/doc-classifier.ts
index eb06ea5..5611a84 100644
--- a/src/doc-classifier.ts
+++ b/src/doc-classifier.ts
@@ -18,13 +18,27 @@ export type DocClassification = {
   shouldDatePrefix: boolean;
 };
 
-export function classifyDoc(relPath: string): DocClassification {
+function normalizeDocsRoot(docsRoot: string): string {
+  const normalized = docsRoot
+    .replace(/\\/g, "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+$/, "");
+  if (!normalized || normalized === ".") return "docs";
+  return normalized;
+}
+
+export function classifyDoc(
+  relPath: string,
+  opts?: { docsRoot?: string },
+): DocClassification {
   const baseName = path.posix.basename(relPath);
   if (!isMarkdownFile(baseName))
     throw new Error(`classifyDoc expected a Markdown file, got: ${relPath}`);
 
+  const docsRoot = normalizeDocsRoot(opts?.docsRoot ?? "docs");
+  const docsPrefix = `${docsRoot}/`;
   const location: DocLocation = relPath.includes("/")
-    ? relPath.startsWith("docs/")
+    ? relPath.startsWith(docsPrefix)
       ? "docs"
       : "other"
     : "root";
diff --git a/src/migrator.ts b/src/migrator.ts
index 98038d5..5ffaa82 100644
--- a/src/migrator.ts
+++ b/src/migrator.ts
@@ -26,6 +26,7 @@ export type FrontmatterAction = {
   title: string;
   author: string;
   date: string;
+  tags?: string[];
 };
 export type MigrationAction =
   | RenameAction
@@ -36,6 +37,7 @@ export type MigrationPlan = {
   repoRootAbs: string;
   trackedSet: Set<string>;
   dirty: boolean;
+  docsRoot: string;
   actions: MigrationAction[];
 };
 
@@ -75,8 +77,9 @@ function yamlQuote(value: string): string {
   return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function yamlList(values: string[]): string {
+  const items = values.map((value) => yamlQuote(value));
+  return `[${items.join(", ")}]`;
 }
 
 type ReferenceReplacement = { from: string; to: string };
@@ -189,18 +192,22 @@ function buildFrontmatter({
   title,
   author,
   date,
+  tags,
 }: {
   title: string;
   author: string;
   date: string;
+  tags?: string[];
 }): string {
-  return [
+  const lines = [
     "---",
     `title: ${yamlQuote(title)}`,
     `author: ${yamlQuote(author)}`,
     `date: ${yamlQuote(date)}`,
-    "---",
-  ].join("\n");
+  ];
+  if (tags && tags.length > 0) lines.push(`tags: ${yamlList(tags)}`);
+  lines.push("---");
+  return lines.join("\n");
 }
 
 async function getFileSystemInfo(
@@ -296,6 +303,66 @@ async function listRootFiles(repoRootAbs: string): Promise<string[]> {
     .filter((name) => !name.startsWith("."));
 }
 
+function normalizeDocsRoot(root: string): string {
+  const normalized = root
+    .replace(/\\/g, "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+$/, "");
+  if (!normalized || normalized === ".") return "docs";
+  return normalized;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function globToRegexSource(pattern: string): string {
+  let out = "";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i]!;
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        const next = pattern[i + 2];
+        if (next === "/") {
+          out += "(?:.*/)?";
+          i += 2;
+        } else {
+          out += ".*";
+          i += 1;
+        }
+        continue;
+      }
+      out += "[^/]*";
+      continue;
+    }
+    if (ch === "?") {
+      out += "[^/]";
+      continue;
+    }
+    out += escapeRegExp(ch);
+  }
+  return out;
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let normalized = pattern.replace(/\\/g, "/").replace(/^\.\/+/, "");
+  normalized = normalized.replace(/\/+$/, "");
+  if (normalized.endsWith("/**")) {
+    const base = normalized.slice(0, -3);
+    return new RegExp(`^${globToRegexSource(base)}(?:/.*)?$`);
+  }
+  return new RegExp(`^${globToRegexSource(normalized)}$`);
+}
+
+function buildIgnoreMatcher(patterns: string[]): (relPath: string) => boolean {
+  if (patterns.length === 0) return () => false;
+  const regexes = patterns.map((pattern) => globToRegExp(pattern));
+  return (relPath: string): boolean => {
+    const normalized = relPath.replace(/\\/g, "/");
+    return regexes.some((regex) => regex.test(normalized));
+  };
+}
+
 export function formatActions(actions: MigrationAction[]): string {
   const lines: string[] = [];
   for (const action of actions) {
@@ -315,6 +382,13 @@ export function formatActions(actions: MigrationAction[]): string {
 
 export type MigrationPlanOptions = {
   cwd?: string;
+  docsRoot?: string;
+  ignoreGlobs?: string[];
+  frontmatterDefaults?: {
+    author?: string;
+    tags?: string[];
+    titlePrefix?: string;
+  };
   moveRootMarkdownToDocs?: boolean;
   renameDocsToDatePrefix?: boolean;
   addFrontmatter?: boolean;
@@ -335,6 +409,9 @@ export async function planMigration(
   options: MigrationPlanOptions = {},
 ): Promise<MigrationPlan> {
   const cwd = options.cwd ?? process.cwd();
+  const docsRoot = normalizeDocsRoot(options.docsRoot ?? "docs");
+  const docsRootPrefix = `${docsRoot}/`;
+  const ignoreMatcher = buildIgnoreMatcher(options.ignoreGlobs ?? []);
   const moveRootMarkdownToDocs = options.moveRootMarkdownToDocs ?? true;
   const renameDocsToDatePrefix = options.renameDocsToDatePrefix ?? true;
   const addFrontmatter = options.addFrontmatter ?? true;
@@ -353,6 +430,7 @@ export async function planMigration(
 
   const rootFiles = await listRootFiles(repoRootAbs);
   const rootMarkdown = rootFiles.filter((f) => {
+    if (ignoreMatcher(f)) return false;
     if (!isMarkdownFile(f)) return false;
     return (
       Boolean(getCanonicalBaseName(f)) ||
@@ -363,17 +441,20 @@ export async function planMigration(
 
   const existingAll = await git.listRepoFiles(repoRootAbs);
   const existingOnDisk: string[] = [];
+  const existingOnDiskAll: string[] = [];
   const totalFiles = existingAll.length;
   for (let idx = 0; idx < existingAll.length; idx++) {
     const filePath = existingAll[idx]!;
-    if (await pathExists(repoRootAbs, filePath)) existingOnDisk.push(filePath);
+    const exists = await pathExists(repoRootAbs, filePath);
+    if (exists) existingOnDiskAll.push(filePath);
+    if (!ignoreMatcher(filePath) && exists) existingOnDisk.push(filePath);
     if (onProgress)
       onProgress({ phase: "scan", current: idx + 1, total: totalFiles });
   }
-  const existingAllSet = new Set(existingOnDisk);
+  const existingAllSet = new Set(existingOnDiskAll);
 
   const docsMarkdown = existingOnDisk.filter(
-    (p) => p.startsWith("docs/") && isMarkdownFile(p),
+    (p) => p.startsWith(docsRootPrefix) && isMarkdownFile(p),
   );
   const candidates = [...new Set([...rootMarkdown, ...docsMarkdown])];
 
@@ -392,7 +473,7 @@ export async function planMigration(
 
   const desiredTargets = new Map<string, string>();
   for (const filePath of candidates) {
-    const classification = classifyDoc(filePath);
+    const classification = classifyDoc(filePath, { docsRoot });
     const base = classification.baseName;
     const desiredMode: RenameCaseMode =
       renameCaseOverrides[filePath] ?? classification.mode;
@@ -427,7 +508,7 @@ export async function planMigration(
         const targetBase = normalizeDatePrefixedDocs
           ? applyRenameCase(base, desiredMode)
           : base;
-        desiredTargets.set(filePath, path.posix.join("docs", targetBase));
+        desiredTargets.set(filePath, path.posix.join(docsRoot, targetBase));
         continue;
       }
 
@@ -439,7 +520,7 @@ export async function planMigration(
         const slug = applyRenameCase(base, desiredMode);
         desiredTargets.set(
           filePath,
-          path.posix.join("docs", `${meta.date}-${slug}`),
+          path.posix.join(docsRoot, `${meta.date}-${slug}`),
         );
         continue;
       }
@@ -565,15 +646,23 @@ export async function planMigration(
       if (hasFrontmatter(content)) continue;
 
       const meta = await getMeta(filePath);
-      const author = meta.author ?? "Unknown <unknown@example.com>";
+      const defaultAuthor = options.frontmatterDefaults?.author;
+      const author =
+        defaultAuthor ?? meta.author ?? "Unknown <unknown@example.com>";
       const date = datePrefix;
-      const title = titleFromMarkdown(content) ?? titleFromSlug(targetBase);
+      const titleFromDoc = titleFromMarkdown(content);
+      let title = titleFromDoc ?? titleFromSlug(targetBase);
+      if (!titleFromDoc && options.frontmatterDefaults?.titlePrefix) {
+        const prefix = options.frontmatterDefaults.titlePrefix.trim();
+        title = `${prefix} ${title}`.trim();
+      }
       frontmatterAdds.push({
         type: "frontmatter",
         path: targetPath,
         title,
         author,
         date,
+        tags: options.frontmatterDefaults?.tags,
       });
     }
   }
@@ -587,9 +676,10 @@ export async function planMigration(
     const searchStrings = [...new Set(finalRenames.map((r) => r.from))];
     const candidatesForScan = new Set<string>();
     for (const filePath of await git.grepFilesFixed(repoRootAbs, searchStrings))
-      candidatesForScan.add(filePath);
+      if (!ignoreMatcher(filePath)) candidatesForScan.add(filePath);
     for (const filePath of existingOnDisk) {
       if (trackedSet.has(filePath)) continue;
+      if (ignoreMatcher(filePath)) continue;
       candidatesForScan.add(filePath);
     }
 
@@ -616,6 +706,7 @@ export async function planMigration(
     repoRootAbs,
     trackedSet,
     dirty,
+    docsRoot,
     actions,
   };
 }
@@ -732,6 +823,7 @@ export async function runMigrationPlan(
       title: action.title,
       author,
       date: action.date,
+      tags: action.tags,
     });
     await writeFrontmatter(plan.repoRootAbs, action.path, frontmatter);
   }
diff --git a/test/integration/config.test.ts b/test/integration/config.test.ts
new file mode 100644
index 0000000..5ef0105
--- /dev/null
+++ b/test/integration/config.test.ts
@@ -0,0 +1,62 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { loadConfig } from "../../src/config.js";
+import { makeTempRepo, writeFile } from "../helpers/repo.js";
+
+test("config: merges repo and local overrides", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(
+    repo.dir,
+    "simpledoc.json",
+    JSON.stringify(
+      {
+        docs: { root: "documentation" },
+        frontmatter: { defaults: { author: "Repo <repo@example.com>" } },
+        check: { ignore: ["docs/generated/**"] },
+        simplelog: { thresholdMinutes: 7 },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  await writeFile(
+    repo.dir,
+    ".simpledoc.local.json",
+    JSON.stringify(
+      {
+        frontmatter: {
+          defaults: { author: "Local <local@example.com>" },
+        },
+        simplelog: { root: "docs/logs/_local/alice", thresholdMinutes: 2 },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  const config = await loadConfig(repo.dir);
+  assert.equal(config.docsRoot, "documentation");
+  assert.equal(config.simplelog.root, "docs/logs/_local/alice");
+  assert.equal(config.simplelog.thresholdMinutes, 2);
+  assert.equal(config.frontmatterDefaults.author, "Local <local@example.com>");
+  assert.deepEqual(config.checkIgnore, ["docs/generated/**"]);
+});
+
+test("config: defaults simplelog root to docs root", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(
+    repo.dir,
+    "simpledoc.json",
+    JSON.stringify({ docs: { root: "documentation" } }, null, 2) + "\n",
+  );
+
+  const config = await loadConfig(repo.dir);
+  assert.equal(config.docsRoot, "documentation");
+  assert.equal(config.simplelog.root, "documentation/logs");
+});
diff --git a/test/integration/migrator.apply.test.ts b/test/integration/migrator.apply.test.ts
index 164f068..e9f6835 100644
--- a/test/integration/migrator.apply.test.ts
+++ b/test/integration/migrator.apply.test.ts
@@ -58,3 +58,30 @@ test("apply: inserts frontmatter using git author and date prefix", async (t) =>
   assert.match(doc, /author: "Alice <alice@example\.com>"/);
   assert.match(doc, /date: "2024-03-02"/);
 });
+
+test("apply: uses frontmatter defaults for author, tags, and title prefix", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(repo.dir, "docs/2024-03-02-some-doc.md", "Body\n");
+  commitAll(repo.dir, {
+    message: "Add date-prefixed doc",
+    author: "Alice <alice@example.com>",
+    dateIso: "2024-04-01T12:00:00Z",
+  });
+
+  const plan = await planMigration({
+    cwd: repo.dir,
+    frontmatterDefaults: {
+      author: "Default <default@example.com>",
+      tags: ["alpha", "beta"],
+      titlePrefix: "Note",
+    },
+  });
+  await runMigrationPlan(plan, { authorOverride: null, authorRewrites: null });
+
+  const doc = await readFile(repo.dir, "docs/2024-03-02-some-doc.md");
+  assert.match(doc, /title: "Note Some Doc"/);
+  assert.match(doc, /author: "Default <default@example\.com>"/);
+  assert.match(doc, /tags: \["alpha", "beta"\]/);
+});
diff --git a/test/integration/migrator.plan.test.ts b/test/integration/migrator.plan.test.ts
index 9d95329..4491651 100644
--- a/test/integration/migrator.plan.test.ts
+++ b/test/integration/migrator.plan.test.ts
@@ -316,3 +316,47 @@ test("plan: resolves rename collisions by uniquifying targets", async (t) => {
     `Expected one target to end with -2.md, got: ${targets.join(", ")}`,
   );
 });
+
+test("plan: respects docsRoot option", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(repo.dir, "documentation/Develop.md", "# Hello\n");
+  commitAll(repo.dir, {
+    message: "Add Develop",
+    author: "Alice <alice@example.com>",
+    dateIso: "2024-01-15T12:00:00Z",
+  });
+
+  const plan = await planMigration({
+    cwd: repo.dir,
+    docsRoot: "documentation",
+  });
+  const renames = plan.actions.filter((a) => a.type === "rename");
+  assert.deepEqual(renames, [
+    {
+      type: "rename",
+      from: "documentation/Develop.md",
+      to: "documentation/2024-01-15-develop.md",
+    },
+  ]);
+});
+
+test("plan: ignores paths matched by ignore globs", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(repo.dir, "docs/generated/Develop.md", "# Hello\n");
+  commitAll(repo.dir, {
+    message: "Add generated doc",
+    author: "Alice <alice@example.com>",
+    dateIso: "2024-01-15T12:00:00Z",
+  });
+
+  const plan = await planMigration({
+    cwd: repo.dir,
+    ignoreGlobs: ["docs/generated/**"],
+  });
+
+  assert.equal(plan.actions.length, 0);
+});

From b93a3ade8aeaddf40ef6909924a3abc315dd306b Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 22:00:07 +0100
Subject: [PATCH 21/26] Refactor config helpers

---
 docs/logs/2026-02-04.md |  10 +++-
 src/cli/log.ts          |  46 +++++-------------
 src/config.ts           | 105 ++++++++++++++++++++++++++++++----------
 src/doc-classifier.ts   |  10 +---
 src/frontmatter.ts      |  42 ++++++++++++++++
 src/ignore.ts           |  52 ++++++++++++++++++++
 src/migrator.ts         |  86 ++++----------------------------
 src/paths.ts            |   8 +++
 8 files changed, 214 insertions(+), 145 deletions(-)
 create mode 100644 src/frontmatter.ts
 create mode 100644 src/ignore.ts
 create mode 100644 src/paths.ts

diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 60521a3..e8f225d 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:44:25+01:00
+updated: 2026-02-04T21:59:30+01:00
 ---
 
 ## 20:35
@@ -59,3 +59,11 @@ Implemented config loading (simpledoc.json + .simpledoc.local.json) with precede
 - Wired docs.root, frontmatter.defaults, check.ignore, and simplelog.\* into CLI + migrator logic.
 - Added config tests plus docsRoot/ignore/frontmatter default coverage.
 - Ran npm test (all passing).
+
+## 21:59
+
+Refactored config validation and shared helpers for docs root, ignore globs, and frontmatter formatting.
+
+- Normalized docs root + simplelog root handling and stricter config type checks.
+- Log frontmatter now uses ordered fields via shared builder.
+- Added shared frontmatter/ignore/path helpers; tests: npm test.
diff --git a/src/cli/log.ts b/src/cli/log.ts
index 9e43b3c..222984e 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -3,6 +3,7 @@ import path from "node:path";
 import process from "node:process";
 
 import { loadConfig } from "../config.js";
+import { buildFrontmatter, type FrontmatterValue } from "../frontmatter.js";
 
 type LogOptions = {
   root?: string;
@@ -153,38 +154,15 @@ function stripLegacyHeader(content: string): string {
   return lines.slice(idx).join("\n");
 }
 
-type FrontmatterValue = string | string[];
-
-function yamlQuote(value: string): string {
-  const s = String(value).replace(/\r?\n/g, " ").trim();
-  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
-function formatFrontmatterValue(value: FrontmatterValue): string {
-  if (Array.isArray(value))
-    return `[${value.map((item) => yamlQuote(item)).join(", ")}]`;
-  return value;
-}
-
-function buildFrontmatter(data: Record<string, FrontmatterValue>): string {
-  const preferredOrder = [
-    "title",
-    "author",
-    "date",
-    "tz",
-    "created",
-    "updated",
-  ];
-  const preferred = preferredOrder.filter((key) => key in data);
-  const extras = Object.keys(data)
-    .filter((key) => !preferredOrder.includes(key))
-    .sort();
-  const keys = [...preferred, ...extras];
-  const lines = keys
-    .map((key) => `${key}: ${formatFrontmatterValue(data[key]!)}`)
-    .filter((line) => !line.endsWith(": "));
-  return `---\n${lines.join("\n")}\n---\n\n`;
-}
+const FRONTMATTER_ORDER = [
+  "title",
+  "author",
+  "date",
+  "tz",
+  "created",
+  "updated",
+  "tags",
+];
 
 function resolveAuthor(): string {
   const name =
@@ -416,7 +394,9 @@ export async function runLog(
     ) {
       updatedFrontmatterData.tags = config.frontmatterDefaults.tags;
     }
-    const updatedFrontmatter = buildFrontmatter(updatedFrontmatterData);
+    const updatedFrontmatter = buildFrontmatter(updatedFrontmatterData, {
+      order: FRONTMATTER_ORDER,
+    });
     const nextContent = joinFrontmatterAndBody(updatedFrontmatter, nextBody);
     await fs.writeFile(filePath, nextContent, "utf8");
     process.stdout.write(`Logged to ${filePath}\n`);
diff --git a/src/config.ts b/src/config.ts
index 3269b3b..fbf7077 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { createGitClient, type GitClient } from "./git.js";
+import { normalizeDocsRoot } from "./paths.js";
 
 type FrontmatterDefaults = {
   author?: string;
@@ -93,11 +94,14 @@ async function readConfigFile(
 }
 
 function normalizeRelPath(
-  input: string | undefined,
+  input: unknown,
   repoRootAbs: string,
   fallback: string,
+  label: string,
 ): string {
-  const trimmed = (input ?? "").trim();
+  if (input === undefined) return fallback;
+  if (typeof input !== "string") throw new Error(`${label} must be a string`);
+  const trimmed = input.trim();
   if (!trimmed) return fallback;
 
   let relPath = trimmed;
@@ -122,20 +126,40 @@ function normalizeTags(value: unknown): string[] | undefined {
   if (value === undefined) return undefined;
   if (!Array.isArray(value))
     throw new Error("frontmatter.defaults.tags must be an array of strings");
-  const tags = value.map((item) => String(item)).filter((item) => item.trim());
+  const tags = value
+    .map((item) => {
+      if (typeof item !== "string")
+        throw new Error(
+          "frontmatter.defaults.tags must be an array of strings",
+        );
+      return item.trim();
+    })
+    .filter((item) => item.length > 0);
   return tags.length > 0 ? tags : undefined;
 }
 
 function normalizeFrontmatterDefaults(value: unknown): FrontmatterDefaults {
-  if (!isPlainObject(value)) return {};
+  if (value === undefined) return {};
+  if (!isPlainObject(value))
+    throw new Error("frontmatter.defaults must be an object");
   const author =
-    typeof value.author === "string" && value.author.trim()
-      ? value.author.trim()
-      : undefined;
+    typeof value.author === "string"
+      ? value.author.trim() || undefined
+      : value.author === undefined
+        ? undefined
+        : (() => {
+            throw new Error("frontmatter.defaults.author must be a string");
+          })();
   const titlePrefix =
-    typeof value.titlePrefix === "string" && value.titlePrefix.trim()
-      ? value.titlePrefix.trim()
-      : undefined;
+    typeof value.titlePrefix === "string"
+      ? value.titlePrefix.trim() || undefined
+      : value.titlePrefix === undefined
+        ? undefined
+        : (() => {
+            throw new Error(
+              "frontmatter.defaults.titlePrefix must be a string",
+            );
+          })();
   const tags = normalizeTags(value.tags);
   return { author, titlePrefix, tags };
 }
@@ -145,17 +169,35 @@ function normalizeCheckIgnore(value: unknown): string[] {
   if (!Array.isArray(value))
     throw new Error("check.ignore must be an array of strings");
   const patterns = value
-    .map((item) => String(item).trim())
+    .map((item) => {
+      if (typeof item !== "string")
+        throw new Error("check.ignore must be an array of strings");
+      return item.trim();
+    })
     .filter((item) => item.length > 0);
   return patterns;
 }
 
 function normalizeThreshold(value: unknown): number {
   if (value === undefined) return DEFAULT_SIMPLELOG_THRESHOLD_MINUTES;
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0)
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
     throw new Error("simplelog.thresholdMinutes must be a number >= 0");
-  return parsed;
+  return value;
+}
+
+function normalizeOptionalString(
+  value: unknown,
+  label: string,
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw new Error(`${label} must be a string`);
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function assertPlainObjectOptional(value: unknown, label: string): void {
+  if (value === undefined) return;
+  if (!isPlainObject(value)) throw new Error(`${label} must be an object`);
 }
 
 export async function loadConfig(
@@ -177,24 +219,37 @@ export async function loadConfig(
   const localConfig = (await readConfigFile(localConfigPath)) ?? {};
   const merged = mergeConfig(repoConfig, localConfig);
 
-  const docsRoot = normalizeRelPath(
-    merged.docs?.root,
-    repoRootAbs,
-    DEFAULT_DOCS_ROOT,
+  assertPlainObjectOptional(merged.docs, "docs");
+  assertPlainObjectOptional(merged.frontmatter, "frontmatter");
+  assertPlainObjectOptional(
+    merged.frontmatter?.defaults,
+    "frontmatter.defaults",
   );
+  assertPlainObjectOptional(merged.check, "check");
+  assertPlainObjectOptional(merged.simplelog, "simplelog");
+
+  const docsRoot = normalizeDocsRoot(
+    normalizeRelPath(
+      merged.docs?.root,
+      repoRootAbs,
+      DEFAULT_DOCS_ROOT,
+      "docs.root",
+    ),
+  );
+  const defaultSimplelogRoot = path.posix.join(docsRoot, "logs");
   const simplelogRoot = normalizeRelPath(
-    merged.simplelog?.root ?? path.posix.join(docsRoot, "logs"),
+    merged.simplelog?.root,
     repoRootAbs,
-    path.posix.join(docsRoot, "logs"),
+    defaultSimplelogRoot,
+    "simplelog.root",
   );
   const thresholdMinutes = normalizeThreshold(
     merged.simplelog?.thresholdMinutes,
   );
-  const timezone =
-    typeof merged.simplelog?.timezone === "string" &&
-    merged.simplelog.timezone.trim()
-      ? merged.simplelog.timezone.trim()
-      : undefined;
+  const timezone = normalizeOptionalString(
+    merged.simplelog?.timezone,
+    "simplelog.timezone",
+  );
 
   const frontmatterDefaults = normalizeFrontmatterDefaults(
     merged.frontmatter?.defaults,
diff --git a/src/doc-classifier.ts b/src/doc-classifier.ts
index 5611a84..0ae4dd2 100644
--- a/src/doc-classifier.ts
+++ b/src/doc-classifier.ts
@@ -6,6 +6,7 @@ import {
   isAllCapsDocBaseName,
   isMarkdownFile,
 } from "./naming.js";
+import { normalizeDocsRoot } from "./paths.js";
 
 export type DocLocation = "root" | "docs" | "other";
 
@@ -18,15 +19,6 @@ export type DocClassification = {
   shouldDatePrefix: boolean;
 };
 
-function normalizeDocsRoot(docsRoot: string): string {
-  const normalized = docsRoot
-    .replace(/\\/g, "/")
-    .replace(/^\.\/+/, "")
-    .replace(/\/+$/, "");
-  if (!normalized || normalized === ".") return "docs";
-  return normalized;
-}
-
 export function classifyDoc(
   relPath: string,
   opts?: { docsRoot?: string },
diff --git a/src/frontmatter.ts b/src/frontmatter.ts
new file mode 100644
index 0000000..fa0999f
--- /dev/null
+++ b/src/frontmatter.ts
@@ -0,0 +1,42 @@
+export type FrontmatterValue = string | string[];
+
+function yamlQuote(value: string): string {
+  const s = String(value).replace(/\r?\n/g, " ").trim();
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function formatArray(values: string[]): string {
+  const rendered = values.map((value) => yamlQuote(value));
+  return `[${rendered.join(", ")}]`;
+}
+
+function formatValue(value: FrontmatterValue, quoteStrings: boolean): string {
+  if (Array.isArray(value)) return formatArray(value);
+  if (quoteStrings) return yamlQuote(value);
+  return value;
+}
+
+function isEmptyValue(value: FrontmatterValue | undefined): boolean {
+  if (value === undefined) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  return value.trim() === "";
+}
+
+export function buildFrontmatter(
+  data: Record<string, FrontmatterValue | undefined>,
+  opts?: { order?: string[]; quoteStrings?: boolean },
+): string {
+  const order = opts?.order ?? [];
+  const quoteStrings = opts?.quoteStrings ?? false;
+  const keys = Object.keys(data).filter((key) => !isEmptyValue(data[key]));
+  const preferred = order.filter((key) => keys.includes(key));
+  const extras = keys.filter((key) => !order.includes(key)).sort();
+  const finalKeys = [...preferred, ...extras];
+
+  const lines = finalKeys.map((key) => {
+    const value = data[key] as FrontmatterValue;
+    return `${key}: ${formatValue(value, quoteStrings)}`;
+  });
+
+  return `---\n${lines.join("\n")}\n---\n\n`;
+}
diff --git a/src/ignore.ts b/src/ignore.ts
new file mode 100644
index 0000000..a3a38b9
--- /dev/null
+++ b/src/ignore.ts
@@ -0,0 +1,52 @@
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function globToRegexSource(pattern: string): string {
+  let out = "";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i]!;
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        const next = pattern[i + 2];
+        if (next === "/") {
+          out += "(?:.*/)?";
+          i += 2;
+        } else {
+          out += ".*";
+          i += 1;
+        }
+        continue;
+      }
+      out += "[^/]*";
+      continue;
+    }
+    if (ch === "?") {
+      out += "[^/]";
+      continue;
+    }
+    out += escapeRegExp(ch);
+  }
+  return out;
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let normalized = pattern.replace(/\\/g, "/").replace(/^\.\/+/, "");
+  normalized = normalized.replace(/\/+$/, "");
+  if (normalized.endsWith("/**")) {
+    const base = normalized.slice(0, -3);
+    return new RegExp(`^${globToRegexSource(base)}(?:/.*)?$`);
+  }
+  return new RegExp(`^${globToRegexSource(normalized)}$`);
+}
+
+export function buildIgnoreMatcher(
+  patterns: string[],
+): (relPath: string) => boolean {
+  if (patterns.length === 0) return () => false;
+  const regexes = patterns.map((pattern) => globToRegExp(pattern));
+  return (relPath: string): boolean => {
+    const normalized = relPath.replace(/\\/g, "/");
+    return regexes.some((regex) => regex.test(normalized));
+  };
+}
diff --git a/src/migrator.ts b/src/migrator.ts
index 5ffaa82..bddc280 100644
--- a/src/migrator.ts
+++ b/src/migrator.ts
@@ -11,6 +11,9 @@ import {
   isLowercaseDocBaseName,
   isMarkdownFile,
 } from "./naming.js";
+import { normalizeDocsRoot } from "./paths.js";
+import { buildIgnoreMatcher } from "./ignore.js";
+import { buildFrontmatter } from "./frontmatter.js";
 
 export type { RenameCaseMode } from "./naming.js";
 
@@ -72,16 +75,6 @@ function hasFrontmatter(content: string): boolean {
   return after.startsWith("---\n") || after.startsWith("---\r\n");
 }
 
-function yamlQuote(value: string): string {
-  const s = String(value).replace(/\r?\n/g, " ").trim();
-  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
-function yamlList(values: string[]): string {
-  const items = values.map((value) => yamlQuote(value));
-  return `[${items.join(", ")}]`;
-}
-
 type ReferenceReplacement = { from: string; to: string };
 
 function buildReferenceReplacements(
@@ -188,7 +181,7 @@ async function readSmallTextFileForReferences(
   return content;
 }
 
-function buildFrontmatter({
+function buildDocFrontmatter({
   title,
   author,
   date,
@@ -199,15 +192,10 @@ function buildFrontmatter({
   date: string;
   tags?: string[];
 }): string {
-  const lines = [
-    "---",
-    `title: ${yamlQuote(title)}`,
-    `author: ${yamlQuote(author)}`,
-    `date: ${yamlQuote(date)}`,
-  ];
-  if (tags && tags.length > 0) lines.push(`tags: ${yamlList(tags)}`);
-  lines.push("---");
-  return lines.join("\n");
+  return buildFrontmatter(
+    { title, author, date, tags },
+    { order: ["title", "author", "date", "tags"], quoteStrings: true },
+  );
 }
 
 async function getFileSystemInfo(
@@ -303,66 +291,10 @@ async function listRootFiles(repoRootAbs: string): Promise<string[]> {
     .filter((name) => !name.startsWith("."));
 }
 
-function normalizeDocsRoot(root: string): string {
-  const normalized = root
-    .replace(/\\/g, "/")
-    .replace(/^\.\/+/, "")
-    .replace(/\/+$/, "");
-  if (!normalized || normalized === ".") return "docs";
-  return normalized;
-}
-
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-function globToRegexSource(pattern: string): string {
-  let out = "";
-  for (let i = 0; i < pattern.length; i += 1) {
-    const ch = pattern[i]!;
-    if (ch === "*") {
-      if (pattern[i + 1] === "*") {
-        const next = pattern[i + 2];
-        if (next === "/") {
-          out += "(?:.*/)?";
-          i += 2;
-        } else {
-          out += ".*";
-          i += 1;
-        }
-        continue;
-      }
-      out += "[^/]*";
-      continue;
-    }
-    if (ch === "?") {
-      out += "[^/]";
-      continue;
-    }
-    out += escapeRegExp(ch);
-  }
-  return out;
-}
-
-function globToRegExp(pattern: string): RegExp {
-  let normalized = pattern.replace(/\\/g, "/").replace(/^\.\/+/, "");
-  normalized = normalized.replace(/\/+$/, "");
-  if (normalized.endsWith("/**")) {
-    const base = normalized.slice(0, -3);
-    return new RegExp(`^${globToRegexSource(base)}(?:/.*)?$`);
-  }
-  return new RegExp(`^${globToRegexSource(normalized)}$`);
-}
-
-function buildIgnoreMatcher(patterns: string[]): (relPath: string) => boolean {
-  if (patterns.length === 0) return () => false;
-  const regexes = patterns.map((pattern) => globToRegExp(pattern));
-  return (relPath: string): boolean => {
-    const normalized = relPath.replace(/\\/g, "/");
-    return regexes.some((regex) => regex.test(normalized));
-  };
-}
-
 export function formatActions(actions: MigrationAction[]): string {
   const lines: string[] = [];
   for (const action of actions) {
@@ -819,7 +751,7 @@ export async function runMigrationPlan(
       options?.authorOverride ??
       options?.authorRewrites?.[action.author] ??
       action.author;
-    const frontmatter = buildFrontmatter({
+    const frontmatter = buildDocFrontmatter({
       title: action.title,
       author,
       date: action.date,
diff --git a/src/paths.ts b/src/paths.ts
new file mode 100644
index 0000000..4e15a76
--- /dev/null
+++ b/src/paths.ts
@@ -0,0 +1,8 @@
+export function normalizeDocsRoot(root?: string): string {
+  const normalized = (root ?? "docs")
+    .replace(/\\/g, "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+$/, "");
+  if (!normalized || normalized === ".") return "docs";
+  return normalized;
+}

From 2b3287337cf50a75eeb757a3f911039de14c444d Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 22:06:37 +0100
Subject: [PATCH 22/26] Allow date-only docs

---
 .husky/pre-commit                      |  2 ++
 README.md                              |  1 +
 docs/SIMPLEDOC_SPEC.md                 |  1 +
 docs/logs/2026-02-04.md                | 11 ++++++++++-
 src/naming.ts                          | 10 +++++-----
 test/integration/migrator.plan.test.ts | 18 ++++++++++++++++++
 6 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/.husky/pre-commit b/.husky/pre-commit
index 8b73430..e537468 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1 +1,3 @@
 npm exec -- lint-staged
+npm run -s build
+node ./dist/bin/simpledoc.js check
diff --git a/README.md b/README.md
index 485a5ff..a1c1d1f 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ Configuration for tooling can be shared in `simpledoc.json` and overridden per-u
 - MUST put date-prefixed files in a top level `docs/` folder, or a subfolder `docs/<topic>/`. Subfolders MAY be nested indefinitely.
 - MUST use ISO 8601 date prefixes (`YYYY-MM-DD`) — the date MUST contain dashes.
 - After the date prefix, lowercase filenames SHOULD use dashes (`-`) as word delimiters (kebab-case). Avoid spaces and underscores.
+- The date prefix MAY be the entire filename (for example, daily logs like `docs/logs/2026-02-04.md`).
 - MUST NOT use capital letters in filename for Latin, Greek, Cyrillic and other writing systems that have lowercase/uppercase distinction.
 - MAY use non-ASCII characters, e.g. `docs/2025-12-22-postmortem-login-ausfälle.md`, `docs/2025-12-22-功能-设计说明.md`.
 - Date-prefixed files SHOULD contain YAML frontmatter with at least `title`, `author` and `date` fields, but we are all people and sometimes don't have time to write a proper frontmatter, so it is not required. E.g.
diff --git a/docs/SIMPLEDOC_SPEC.md b/docs/SIMPLEDOC_SPEC.md
index 1a720ac..9e8e1cf 100644
--- a/docs/SIMPLEDOC_SPEC.md
+++ b/docs/SIMPLEDOC_SPEC.md
@@ -17,6 +17,7 @@ SimpleDoc defines two types of files:
 - MUST put date-prefixed files in a top level `docs/` folder, or a subfolder `docs/<topic>/`. Subfolders MAY be nested indefinitely.
 - MUST use ISO 8601 date prefixes (`YYYY-MM-DD`) — the date MUST contain dashes.
 - After the date prefix, lowercase filenames SHOULD use dashes (`-`) as word delimiters (kebab-case). Avoid spaces and underscores.
+- The date prefix MAY be the entire filename (for example, daily logs like `docs/logs/2026-02-04.md`).
 - MUST NOT use capital letters in filename for Latin, Greek, Cyrillic and other writing systems that have lowercase/uppercase distinction.
 - MAY use non-ASCII characters, e.g. `docs/2025-12-22-postmortem-login-ausfälle.md`, `docs/2025-12-22-功能-设计说明.md`.
 - Date-prefixed files SHOULD contain YAML frontmatter with at least `title`, `author` and `date` fields, but we are all people and sometimes don't have time to write a proper frontmatter, so it is not required. E.g.
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index e8f225d..a3222b5 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T21:59:30+01:00
+updated: 2026-02-04T22:06:26+01:00
 ---
 
 ## 20:35
@@ -67,3 +67,12 @@ Refactored config validation and shared helpers for docs root, ignore globs, and
 - Normalized docs root + simplelog root handling and stricter config type checks.
 - Log frontmatter now uses ordered fields via shared builder.
 - Added shared frontmatter/ignore/path helpers; tests: npm test.
+
+## 22:06
+
+Allowed date-only filenames for SimpleDoc (e.g., SimpleLog daily files) and updated tooling.
+
+- Updated SimpleDoc spec + README to allow date-only docs.
+- Naming normalization now keeps date-only filenames; added plan test.
+- Added simpledoc check to pre-commit hook.
+- Tests: npm test.
diff --git a/src/naming.ts b/src/naming.ts
index 32ab242..e792820 100644
--- a/src/naming.ts
+++ b/src/naming.ts
@@ -119,13 +119,13 @@ function normalizeBaseName(baseName: string, mode: RenameCaseMode): string {
 
   const dateParts = parseDatePrefixedStem(stem);
   if (dateParts) {
-    const fallback = mode === "capitalized" ? "UNTITLED" : "untitled";
-    const rest = dateParts.rest || fallback;
+    if (!dateParts.rest) return `${dateParts.date}${ext}`;
     const restNormalized =
       mode === "capitalized"
-        ? normalizeCapitalizedStem(rest)
-        : normalizeLowercaseStem(rest);
-    return `${dateParts.date}-${restNormalized || fallback}${ext}`;
+        ? normalizeCapitalizedStem(dateParts.rest)
+        : normalizeLowercaseStem(dateParts.rest);
+    if (!restNormalized) return `${dateParts.date}${ext}`;
+    return `${dateParts.date}-${restNormalized}${ext}`;
   }
 
   const normalizedStem =
diff --git a/test/integration/migrator.plan.test.ts b/test/integration/migrator.plan.test.ts
index 4491651..bb36ece 100644
--- a/test/integration/migrator.plan.test.ts
+++ b/test/integration/migrator.plan.test.ts
@@ -114,6 +114,24 @@ test("plan: treats YYYY-MM-DD_ as date-prefixed and normalizes separators", asyn
   ]);
 });
 
+test("plan: allows date-only docs without slug", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(repo.dir, "docs/logs/2024-06-01.md", "# Log\n");
+  commitAll(repo.dir, {
+    message: "Add date-only log",
+    author: "Alice <alice@example.com>",
+    dateIso: "2024-06-10T12:00:00Z",
+  });
+
+  const plan = await planMigration({ cwd: repo.dir });
+  const renames = plan.actions.filter(
+    (a) => a.type === "rename" && a.from === "docs/logs/2024-06-01.md",
+  );
+  assert.deepEqual(renames, []);
+});
+
 test("plan: keeps YYYY-MM-DD prefix dashes even in capitalized mode", async (t) => {
   const repo = await makeTempRepo();
   t.after(repo.cleanup);

From b13abad2d9d3f5eccb72aa8c6fe37f0b19bf0134 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 22:09:51 +0100
Subject: [PATCH 23/26] Refactor frontmatter helpers

---
 .husky/pre-commit       |  4 +--
 docs/logs/2026-02-04.md |  8 +++++-
 package.json            |  1 +
 src/cli/log.ts          | 57 +++++++----------------------------------
 src/frontmatter.ts      | 46 +++++++++++++++++++++++++++++++++
 src/migrator.ts         |  4 +--
 6 files changed, 66 insertions(+), 54 deletions(-)

diff --git a/.husky/pre-commit b/.husky/pre-commit
index e537468..599bf0a 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,3 +1 @@
-npm exec -- lint-staged
-npm run -s build
-node ./dist/bin/simpledoc.js check
+npm run -s precommit
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index a3222b5..99a6c79 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T22:06:26+01:00
+updated: 2026-02-04T22:09:42+01:00
 ---
 
 ## 20:35
@@ -76,3 +76,9 @@ Allowed date-only filenames for SimpleDoc (e.g., SimpleLog daily files) and upda
 - Naming normalization now keeps date-only filenames; added plan test.
 - Added simpledoc check to pre-commit hook.
 - Tests: npm test.
+
+Refactored pre-commit to run a single npm script, centralized frontmatter field order, and moved frontmatter parsing into a shared helper.
+
+- Added npm script precommit and updated .husky/pre-commit.
+- Exported frontmatter order constants + parse helper in src/frontmatter.ts; log/migrator now reuse.
+- Tests: npm test.
diff --git a/package.json b/package.json
index fbf7081..47e1fae 100644
--- a/package.json
+++ b/package.json
@@ -31,6 +31,7 @@
     "lint": "eslint . --max-warnings 0",
     "prepack": "npm run build",
     "prepare": "husky",
+    "precommit": "npm exec -- lint-staged && npm run -s build && node ./dist/bin/simpledoc.js check",
     "release": "release-it",
     "release:ci": "release-it --ci",
     "migrate": "npm run -s build && node ./dist/bin/simpledoc.js migrate",
diff --git a/src/cli/log.ts b/src/cli/log.ts
index 222984e..fb7822d 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -3,7 +3,12 @@ import path from "node:path";
 import process from "node:process";
 
 import { loadConfig } from "../config.js";
-import { buildFrontmatter, type FrontmatterValue } from "../frontmatter.js";
+import {
+  buildFrontmatter,
+  type FrontmatterValue,
+  parseFrontmatterBlock,
+  SIMPLELOG_FRONTMATTER_ORDER,
+} from "../frontmatter.js";
 
 type LogOptions = {
   root?: string;
@@ -17,12 +22,6 @@ type LogClock = {
   offset: string;
 };
 
-type Frontmatter = {
-  data: Record<string, string>;
-  body: string;
-  hasFrontmatter: boolean;
-};
-
 const ENTRY_RE = /^-?\s*(\d{2}:\d{2}(?::\d{2})?)(Z|[+-]\d{2}:\d{2})\b/;
 const SECTION_RE = /^##\s+(\d{2}):(\d{2})(?::\d{2})?\s*$/;
 
@@ -105,34 +104,6 @@ function safeClockForTimeZone(now: Date, timeZone: string): LogClock | null {
   }
 }
 
-function parseFrontmatter(content: string): Frontmatter {
-  const lines = content.split(/\r?\n/);
-  if (lines[0] !== "---") {
-    return { data: {}, body: content, hasFrontmatter: false };
-  }
-
-  let end = -1;
-  for (let i = 1; i < lines.length; i += 1) {
-    if (lines[i] === "---") {
-      end = i;
-      break;
-    }
-  }
-
-  if (end === -1) {
-    return { data: {}, body: content, hasFrontmatter: false };
-  }
-
-  const data: Record<string, string> = {};
-  for (const line of lines.slice(1, end)) {
-    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (match) data[match[1]] = match[2];
-  }
-
-  const body = lines.slice(end + 1).join("\n");
-  return { data, body, hasFrontmatter: true };
-}
-
 function stripLegacyHeader(content: string): string {
   const lines = content.split(/\r?\n/);
   if (!/^#\s+\d{4}-\d{2}-\d{2}\s*$/.test(lines[0] ?? "")) return content;
@@ -154,16 +125,6 @@ function stripLegacyHeader(content: string): string {
   return lines.slice(idx).join("\n");
 }
 
-const FRONTMATTER_ORDER = [
-  "title",
-  "author",
-  "date",
-  "tz",
-  "created",
-  "updated",
-  "tags",
-];
-
 function resolveAuthor(): string {
   const name =
     process.env.GIT_AUTHOR_NAME ||
@@ -312,7 +273,7 @@ export async function runLog(
         throw err;
     }
 
-    let parsed = parseFrontmatter(content);
+    let parsed = parseFrontmatterBlock(content);
 
     if (fileExists && parsed.hasFrontmatter && parsed.data.tz) {
       const desiredTz = parsed.data.tz;
@@ -337,7 +298,7 @@ export async function runLog(
               fileExists = false;
               content = "";
             }
-            parsed = parseFrontmatter(content);
+            parsed = parseFrontmatterBlock(content);
           }
         }
       }
@@ -395,7 +356,7 @@ export async function runLog(
       updatedFrontmatterData.tags = config.frontmatterDefaults.tags;
     }
     const updatedFrontmatter = buildFrontmatter(updatedFrontmatterData, {
-      order: FRONTMATTER_ORDER,
+      order: SIMPLELOG_FRONTMATTER_ORDER,
     });
     const nextContent = joinFrontmatterAndBody(updatedFrontmatter, nextBody);
     await fs.writeFile(filePath, nextContent, "utf8");
diff --git a/src/frontmatter.ts b/src/frontmatter.ts
index fa0999f..72df609 100644
--- a/src/frontmatter.ts
+++ b/src/frontmatter.ts
@@ -1,5 +1,23 @@
 export type FrontmatterValue = string | string[];
 
+export type ParsedFrontmatter = {
+  data: Record<string, string>;
+  body: string;
+  hasFrontmatter: boolean;
+};
+
+export const DOC_FRONTMATTER_ORDER = ["title", "author", "date", "tags"];
+
+export const SIMPLELOG_FRONTMATTER_ORDER = [
+  "title",
+  "author",
+  "date",
+  "tz",
+  "created",
+  "updated",
+  "tags",
+];
+
 function yamlQuote(value: string): string {
   const s = String(value).replace(/\r?\n/g, " ").trim();
   return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
@@ -40,3 +58,31 @@ export function buildFrontmatter(
 
   return `---\n${lines.join("\n")}\n---\n\n`;
 }
+
+export function parseFrontmatterBlock(content: string): ParsedFrontmatter {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== "---") {
+    return { data: {}, body: content, hasFrontmatter: false };
+  }
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i] === "---") {
+      end = i;
+      break;
+    }
+  }
+
+  if (end === -1) {
+    return { data: {}, body: content, hasFrontmatter: false };
+  }
+
+  const data: Record<string, string> = {};
+  for (const line of lines.slice(1, end)) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) data[match[1]] = match[2];
+  }
+
+  const body = lines.slice(end + 1).join("\n");
+  return { data, body, hasFrontmatter: true };
+}
diff --git a/src/migrator.ts b/src/migrator.ts
index bddc280..c26e400 100644
--- a/src/migrator.ts
+++ b/src/migrator.ts
@@ -13,7 +13,7 @@ import {
 } from "./naming.js";
 import { normalizeDocsRoot } from "./paths.js";
 import { buildIgnoreMatcher } from "./ignore.js";
-import { buildFrontmatter } from "./frontmatter.js";
+import { buildFrontmatter, DOC_FRONTMATTER_ORDER } from "./frontmatter.js";
 
 export type { RenameCaseMode } from "./naming.js";
 
@@ -194,7 +194,7 @@ function buildDocFrontmatter({
 }): string {
   return buildFrontmatter(
     { title, author, date, tags },
-    { order: ["title", "author", "date", "tags"], quoteStrings: true },
+    { order: DOC_FRONTMATTER_ORDER, quoteStrings: true },
   );
 }
 

From a96b919ce5523e1de7cdd029ee3dab6157ff4f7c Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 22:14:12 +0100
Subject: [PATCH 24/26] Use npx in CLI guidance

---
 docs/SIMPLEDOC_CONFIG_SPEC.md | 4 ++--
 docs/logs/2026-02-04.md       | 9 ++++++++-
 src/cli/check.ts              | 2 +-
 src/cli/install.ts            | 8 +++++---
 src/cli/migrate.ts            | 2 +-
 5 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/docs/SIMPLEDOC_CONFIG_SPEC.md b/docs/SIMPLEDOC_CONFIG_SPEC.md
index 723da8f..8ba5c91 100644
--- a/docs/SIMPLEDOC_CONFIG_SPEC.md
+++ b/docs/SIMPLEDOC_CONFIG_SPEC.md
@@ -59,7 +59,7 @@ Top-level object. Current keys:
 - **Meaning:** Root directory for SimpleDoc-managed documentation.
 - **Resolution:** If relative, it is resolved from the repo root.
 - **Default:** `docs`
-- **Notes:** Tools like `simpledoc check` and `simpledoc migrate` SHOULD treat this as the documentation root.
+- **Notes:** Tools like `npx -y @simpledoc/simpledoc check` and `npx -y @simpledoc/simpledoc migrate` SHOULD treat this as the documentation root.
 
 ### frontmatter.defaults
 
@@ -76,7 +76,7 @@ Supported keys:
 ### check.ignore
 
 - **Type:** array of strings
-- **Meaning:** Glob-like patterns to ignore when scanning for violations in `simpledoc check` (and optionally other scans).
+- **Meaning:** Glob-like patterns to ignore when scanning for violations in `npx -y @simpledoc/simpledoc check` (and optionally other scans).
 - **Resolution:** Patterns are matched relative to the repo root.
 - **Notes:** Ignored paths SHOULD be skipped entirely during scans.
 
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index 99a6c79..d260d95 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T22:09:42+01:00
+updated: 2026-02-04T22:14:03+01:00
 ---
 
 ## 20:35
@@ -82,3 +82,10 @@ Refactored pre-commit to run a single npm script, centralized frontmatter field
 - Added npm script precommit and updated .husky/pre-commit.
 - Exported frontmatter order constants + parse helper in src/frontmatter.ts; log/migrator now reuse.
 - Tests: npm test.
+
+Updated CLI instruction strings to use npx with the package name for migrate guidance.
+
+- check/install outputs now say `npx -y @simpledoc/simpledoc migrate`.
+- migrate/install intro labels updated to show the npx command.
+- Config spec references updated.
+- Tests: npm test.
diff --git a/src/cli/check.ts b/src/cli/check.ts
index 088616d..7b12ef9 100644
--- a/src/cli/check.ts
+++ b/src/cli/check.ts
@@ -81,7 +81,7 @@ export async function runCheck(): Promise<void> {
       process.stdout.write(`${limited}\n\n`);
     }
 
-    process.stdout.write("Run `simpledoc migrate` to fix.\n");
+    process.stdout.write("Run `npx -y @simpledoc/simpledoc migrate` to fix.\n");
     process.exitCode = 1;
   } catch (err) {
     process.stderr.write(`${getErrorMessage(err)}\n`);
diff --git a/src/cli/install.ts b/src/cli/install.ts
index e00eefb..5582e19 100644
--- a/src/cli/install.ts
+++ b/src/cli/install.ts
@@ -153,7 +153,9 @@ export async function runInstall(options: InstallOptions): Promise<void> {
       }
       if (migrationInfo.hasIssues) {
         printMigrationSummary(migrationInfo, false);
-        process.stdout.write("Run `simpledoc migrate` to fix.\n");
+        process.stdout.write(
+          "Run `npx -y @simpledoc/simpledoc migrate` to fix.\n",
+        );
       } else {
         process.stdout.write(
           "Done. Review with `git status` / `git diff` and commit when ready.\n",
@@ -162,7 +164,7 @@ export async function runInstall(options: InstallOptions): Promise<void> {
       return;
     }
 
-    intro("simpledoc install");
+    intro("npx -y @simpledoc/simpledoc install");
 
     if (installActionsAll.length > 0) {
       const installSel = await runInstallSteps(installStatus);
@@ -199,7 +201,7 @@ export async function runInstall(options: InstallOptions): Promise<void> {
         process.stdout.write(`${limited}\n\n`);
       }
       const migrateNow = await promptConfirm(
-        "Run `simpledoc migrate` now?",
+        "Run `npx -y @simpledoc/simpledoc migrate` now?",
         true,
       );
       if (migrateNow === null) return abort("Operation cancelled.");
diff --git a/src/cli/migrate.ts b/src/cli/migrate.ts
index 8458e8d..f63d325 100644
--- a/src/cli/migrate.ts
+++ b/src/cli/migrate.ts
@@ -256,7 +256,7 @@ export async function runMigrate(options: MigrateOptions): Promise<void> {
       return;
     }
 
-    intro("simpledoc migrate");
+    intro("npx -y @simpledoc/simpledoc migrate");
 
     if (planAll.dirty && !options.force) {
       const contDirty = await promptConfirm(

From 38113ec3fb529df333c23db050ca4801c13aac08 Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 22:19:22 +0100
Subject: [PATCH 25/26] Add config and log tests

---
 docs/logs/2026-02-04.md              |  9 ++-
 test/integration/config.test.ts      | 46 +++++++++++++++
 test/integration/frontmatter.test.ts | 46 +++++++++++++++
 test/integration/log.test.ts         | 86 ++++++++++++++++++++++++++++
 4 files changed, 186 insertions(+), 1 deletion(-)
 create mode 100644 test/integration/frontmatter.test.ts
 create mode 100644 test/integration/log.test.ts

diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index d260d95..a05f6bf 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,7 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T22:14:03+01:00
+updated: 2026-02-04T22:18:41+01:00
 ---
 
 ## 20:35
@@ -89,3 +89,10 @@ Updated CLI instruction strings to use npx with the package name for migrate gui
 - migrate/install intro labels updated to show the npx command.
 - Config spec references updated.
 - Tests: npm test.
+
+Added tests for config validation errors, frontmatter helpers, and SimpleLog threshold section behavior.
+
+- New config error tests for invalid types.
+- New frontmatter tests for ordered output + parsing.
+- New log test with mocked time to verify threshold-based sections.
+- Tests: npm test.
diff --git a/test/integration/config.test.ts b/test/integration/config.test.ts
index 5ef0105..e9989e4 100644
--- a/test/integration/config.test.ts
+++ b/test/integration/config.test.ts
@@ -60,3 +60,49 @@ test("config: defaults simplelog root to docs root", async (t) => {
   assert.equal(config.docsRoot, "documentation");
   assert.equal(config.simplelog.root, "documentation/logs");
 });
+
+test("config: rejects invalid value types", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(
+    repo.dir,
+    "simpledoc.json",
+    JSON.stringify(
+      {
+        docs: { root: 123 },
+        check: { ignore: "docs/generated/**" },
+        simplelog: { thresholdMinutes: "5" },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  await assert.rejects(
+    () => loadConfig(repo.dir),
+    /docs\.root must be a string/,
+  );
+});
+
+test("config: rejects invalid nested values", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(
+    repo.dir,
+    "simpledoc.json",
+    JSON.stringify(
+      {
+        frontmatter: { defaults: { author: 42, tags: ["ok", 1] } },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  await assert.rejects(
+    () => loadConfig(repo.dir),
+    /frontmatter\.defaults\.author must be a string/,
+  );
+});
diff --git a/test/integration/frontmatter.test.ts b/test/integration/frontmatter.test.ts
new file mode 100644
index 0000000..53f4e43
--- /dev/null
+++ b/test/integration/frontmatter.test.ts
@@ -0,0 +1,46 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  buildFrontmatter,
+  parseFrontmatterBlock,
+  DOC_FRONTMATTER_ORDER,
+} from "../../src/frontmatter.js";
+
+test("frontmatter: builds ordered doc frontmatter", async () => {
+  const fm = buildFrontmatter(
+    {
+      title: "Hello",
+      author: "Alice <alice@example.com>",
+      date: "2026-02-04",
+      tags: ["alpha", "beta"],
+      extra: "note",
+    },
+    { order: DOC_FRONTMATTER_ORDER, quoteStrings: true },
+  );
+
+  const lines = fm.trim().split("\n");
+  assert.equal(lines[0], "---");
+  const keys = lines.slice(1, 6).map((line) => line.split(":")[0]);
+  assert.deepEqual(keys, ["title", "author", "date", "tags", "extra"]);
+  assert.match(fm, /tags: \["alpha", "beta"\]/);
+});
+
+test("frontmatter: parses a frontmatter block", async () => {
+  const content = [
+    "---",
+    "title: Test Doc",
+    "author: Someone <some@example.com>",
+    "date: 2026-02-04",
+    "---",
+    "",
+    "Body line",
+    "",
+  ].join("\n");
+
+  const parsed = parseFrontmatterBlock(content);
+  assert.equal(parsed.hasFrontmatter, true);
+  assert.equal(parsed.data.title, "Test Doc");
+  assert.equal(parsed.data.author, "Someone <some@example.com>");
+  assert.match(parsed.body, /Body line/);
+});
diff --git a/test/integration/log.test.ts b/test/integration/log.test.ts
new file mode 100644
index 0000000..8e74b49
--- /dev/null
+++ b/test/integration/log.test.ts
@@ -0,0 +1,86 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { runLog } from "../../src/cli/log.js";
+import { makeTempRepo, readFile, writeFile } from "../helpers/repo.js";
+
+async function withMockedDate(
+  iso: string,
+  fn: () => Promise<void>,
+): Promise<void> {
+  const RealDate = Date;
+  const fixed = new RealDate(iso);
+  const fixedMs = fixed.getTime();
+  class MockDate extends RealDate {
+    constructor(...args: unknown[]) {
+      if (args.length === 0) {
+        super(fixedMs);
+        return;
+      }
+      if (args.length === 1) {
+        super(args[0] as string | number | Date);
+        return;
+      }
+      const [year, month, date, hours, minutes, seconds, ms] = args as number[];
+      super(year, month, date, hours, minutes, seconds, ms);
+    }
+
+    static now(): number {
+      return fixedMs;
+    }
+  }
+
+  globalThis.Date = MockDate as DateConstructor;
+  try {
+    await fn();
+  } finally {
+    globalThis.Date = RealDate;
+  }
+}
+
+test("log: starts a new section after the threshold", async (t) => {
+  const repo = await makeTempRepo();
+  t.after(repo.cleanup);
+
+  await writeFile(
+    repo.dir,
+    "simpledoc.json",
+    JSON.stringify(
+      {
+        simplelog: {
+          root: "docs/logs",
+          timezone: "UTC",
+          thresholdMinutes: 5,
+        },
+        frontmatter: { defaults: { author: "Test <test@example.com>" } },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  const originalCwd = process.cwd();
+  t.after(() => process.chdir(originalCwd));
+  process.chdir(repo.dir);
+
+  await withMockedDate("2026-02-04T12:00:00Z", async () => {
+    await runLog("First entry", {});
+  });
+
+  await withMockedDate("2026-02-04T12:03:00Z", async () => {
+    await runLog("Second entry", {});
+  });
+
+  await withMockedDate("2026-02-04T12:10:00Z", async () => {
+    await runLog("Third entry", {});
+  });
+
+  const content = await readFile(repo.dir, "docs/logs/2026-02-04.md");
+  const sectionCount = (content.match(/^## /gm) ?? []).length;
+  assert.equal(sectionCount, 2);
+  assert.match(content, /^## 12:00/m);
+  assert.match(content, /^## 12:10/m);
+  assert.match(content, /First entry/);
+  assert.match(content, /Second entry/);
+  assert.match(content, /Third entry/);
+});

From 605d26627321e094bb4ac6b6af17566dce75bceb Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Wed, 4 Feb 2026 22:29:03 +0100
Subject: [PATCH 26/26] Track SimpleLog section start

---
 docs/SIMPLELOG_SPEC.md       |  6 +++-
 docs/logs/2026-02-04.md      | 14 +++++++++-
 src/cli/log.ts               | 53 +++++++++++++++++++-----------------
 src/frontmatter.ts           |  1 +
 test/integration/log.test.ts |  4 +++
 5 files changed, 51 insertions(+), 27 deletions(-)

diff --git a/docs/SIMPLELOG_SPEC.md b/docs/SIMPLELOG_SPEC.md
index deebc5a..f200f6b 100644
--- a/docs/SIMPLELOG_SPEC.md
+++ b/docs/SIMPLELOG_SPEC.md
@@ -31,6 +31,7 @@ Required fields:
 
 Optional fields:
 
+- `last_section`: ISO-8601 timestamp with offset (start time of the latest section).
 - `updated`: ISO-8601 timestamp with offset.
 
 Example:
@@ -42,6 +43,7 @@ author: Jane Doe <jane@example.com>
 date: 2025-12-01
 tz: Europe/Berlin
 created: 2025-12-01T00:00:00+01:00
+last_section: 2025-12-01T09:13:00+01:00
 ---
 ```
 
@@ -131,8 +133,9 @@ When the CLI writes an entry (config is resolved via `simpledoc.json` / `.simple
 3. If the file does not exist, create it with the required frontmatter.
 4. Start a new session section when either:
    - no section exists yet, or
-   - the last entry is older than the threshold (for example, 5 minutes).
+   - the last section start time is older than the threshold (for example, 5 minutes).
      The new section title MUST be the current local time in `HH:MM` format.
+     CLI implementations SHOULD store the section start time in frontmatter as `last_section` and use it for threshold comparisons.
 5. Ensure there is a blank line between the last existing line and the new entry.
 6. Append the new entry block using the exact input text (no indentation changes).
 
@@ -149,6 +152,7 @@ author: Jane Doe <jane@example.com>
 date: 2025-12-01
 tz: Europe/Berlin
 created: 2025-12-01T00:00:00+01:00
+last_section: 2025-12-01T14:27:00+01:00
 ---
 
 ## 09:13
diff --git a/docs/logs/2026-02-04.md b/docs/logs/2026-02-04.md
index a05f6bf..f701d2b 100644
--- a/docs/logs/2026-02-04.md
+++ b/docs/logs/2026-02-04.md
@@ -4,7 +4,8 @@ author: Onur Solmaz <info@solmaz.io>
 date: 2026-02-04
 tz: Europe/Berlin
 created: 2026-02-04T20:35:26+01:00
-updated: 2026-02-04T22:18:41+01:00
+last_section: 2026-02-04T22:27:00+01:00
+updated: 2026-02-04T22:28:43+01:00
 ---
 
 ## 20:35
@@ -96,3 +97,14 @@ Added tests for config validation errors, frontmatter helpers, and SimpleLog thr
 - New frontmatter tests for ordered output + parsing.
 - New log test with mocked time to verify threshold-based sections.
 - Tests: npm test.
+
+## 22:27
+
+Updated SimpleLog section thresholding to use a frontmatter `last_section` timestamp and documented it in the spec.
+
+- CLI now compares threshold against last_section (or last section heading if missing).
+- Frontmatter order includes last_section; updated log test to assert it.
+- Spec now documents last_section as optional frontmatter.
+- Tests: npm test.
+
+Rebuilt CLI output so logs now write `last_section` to frontmatter.
diff --git a/src/cli/log.ts b/src/cli/log.ts
index fb7822d..2f8160a 100644
--- a/src/cli/log.ts
+++ b/src/cli/log.ts
@@ -22,7 +22,6 @@ type LogClock = {
   offset: string;
 };
 
-const ENTRY_RE = /^-?\s*(\d{2}:\d{2}(?::\d{2})?)(Z|[+-]\d{2}:\d{2})\b/;
 const SECTION_RE = /^##\s+(\d{2}):(\d{2})(?::\d{2})?\s*$/;
 
 function getErrorMessage(err: unknown): string {
@@ -175,25 +174,20 @@ function normalizeFrontmatter(
   return { data: next, changed };
 }
 
-function findLastSection(lines: string[]): string | null {
-  for (let i = lines.length - 1; i >= 0; i -= 1) {
-    const line = lines[i] ?? "";
-    const match = line.match(SECTION_RE);
-    if (match) return `## ${match[1]}:${match[2]}`;
-  }
-  return null;
-}
+type SectionTimestamp = { date: Date; value: string };
 
-function findLastEntryTime(lines: string[], date: string): Date | null {
+function findLastSectionTimestamp(
+  lines: string[],
+  clock: LogClock,
+): SectionTimestamp | null {
   for (let i = lines.length - 1; i >= 0; i -= 1) {
     const line = lines[i] ?? "";
-    const match = line.match(ENTRY_RE);
+    const match = line.match(SECTION_RE);
     if (!match) continue;
-    const time = match[1];
-    const offset = match[2];
-    const iso = `${date}T${time}${offset}`;
-    const parsed = new Date(iso);
-    if (!Number.isNaN(parsed.getTime())) return parsed;
+    const time = `${match[1]}:${match[2]}:00`;
+    const value = `${clock.date}T${time}${clock.offset}`;
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) return { date: parsed, value };
   }
   return null;
 }
@@ -321,15 +315,16 @@ export async function runLog(
       config.frontmatterDefaults.titlePrefix,
     );
     const lines = body.split(/\r?\n/);
-    const lastSection = findLastSection(lines);
-    const lastEntry =
-      parseIsoTimestamp(parsed.data.updated) ??
-      parseIsoTimestamp(parsed.data.created) ??
-      findLastEntryTime(lines, clock.date);
-
-    let needsSection = !lastSection || !lastEntry;
-    if (!needsSection && thresholdMinutes > 0 && lastEntry) {
-      const diffMs = now.getTime() - lastEntry.getTime();
+    const lastSectionFromHeading = findLastSectionTimestamp(lines, clock);
+    const lastSectionFromFrontmatter = parseIsoTimestamp(
+      parsed.data.last_section,
+    );
+    const lastSection =
+      lastSectionFromFrontmatter ?? lastSectionFromHeading?.date ?? null;
+
+    let needsSection = !lastSection;
+    if (!needsSection && thresholdMinutes > 0 && lastSection) {
+      const diffMs = now.getTime() - lastSection.getTime();
       if (diffMs >= thresholdMinutes * 60_000) needsSection = true;
     }
 
@@ -349,6 +344,14 @@ export async function runLog(
       ...normalized.data,
       updated,
     };
+    if (needsSection) {
+      updatedFrontmatterData.last_section = updated;
+    } else if (
+      !("last_section" in updatedFrontmatterData) &&
+      lastSectionFromHeading
+    ) {
+      updatedFrontmatterData.last_section = lastSectionFromHeading.value;
+    }
     if (
       !("tags" in updatedFrontmatterData) &&
       config.frontmatterDefaults.tags
diff --git a/src/frontmatter.ts b/src/frontmatter.ts
index 72df609..d6034f9 100644
--- a/src/frontmatter.ts
+++ b/src/frontmatter.ts
@@ -14,6 +14,7 @@ export const SIMPLELOG_FRONTMATTER_ORDER = [
   "date",
   "tz",
   "created",
+  "last_section",
   "updated",
   "tags",
 ];
diff --git a/test/integration/log.test.ts b/test/integration/log.test.ts
index 8e74b49..6f00e1c 100644
--- a/test/integration/log.test.ts
+++ b/test/integration/log.test.ts
@@ -2,6 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import { runLog } from "../../src/cli/log.js";
+import { parseFrontmatterBlock } from "../../src/frontmatter.js";
 import { makeTempRepo, readFile, writeFile } from "../helpers/repo.js";
 
 async function withMockedDate(
@@ -83,4 +84,7 @@ test("log: starts a new section after the threshold", async (t) => {
   assert.match(content, /First entry/);
   assert.match(content, /Second entry/);
   assert.match(content, /Third entry/);
+
+  const parsed = parseFrontmatterBlock(content);
+  assert.equal(parsed.data.last_section, "2026-02-04T12:10:00Z");
 });