Add SimpleDoc/SimpleLog spec (#13)

* Add SimpleDoc/SimpleLog spec

* Normalize SimpleLog spec

* Remove non-ASCII from SimpleLog spec

* Rename SimpleLog spec file

* Align SimpleLog spec title

* Add simpledoc log command

* Support multiline simpledoc log entries

* Auto-read stdin for simpledoc log

* Revise SimpleLog format and frontmatter

* Adjust SimpleLog entry formatting

* Remove auto timestamps from SimpleLog

* Log latest SimpleLog CLI tests

* Mention SimpleLog spec in README

* Document SimpleLog usage in skill

* Add agent logging guidance to skill

* Log ongoing progress in skill guidance

* Broaden skill logging guidance

* Document SimpleDoc config files

* Expand SimpleDoc config spec

* Add config support for SimpleDoc tools

* Refactor config helpers

* Allow date-only docs

* Refactor frontmatter helpers

* Use npx in CLI guidance

* Add config and log tests

* Track SimpleLog section start

Author: osolmaz

.gitignore

@@ -2,3 +2,4 @@
 node_modules
 dist
 dist-test
+.simpledoc.local.json

.husky/pre-commit

@@ -1 +1 @@
-npm exec -- lint-staged
+npm run -s precommit

README.md

@@ -11,12 +11,16 @@ 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`.
+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
 
 - Date-prefixed Markdown files SHOULD be used for most documents that are tied to a specific time.
 - 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.

docs/SIMPLEDOC_CONFIG_SPEC.md

@@ -0,0 +1,155 @@
+# 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
+{
+  "docs": {
+    "root": "docs"
+  },
+  "frontmatter": {
+    "defaults": {
+      "author": "Jane Doe <[email protected]>",
+      "tags": ["docs", "simpledoc"],
+      "titlePrefix": "Daily Log"
+    }
+  },
+  "check": {
+    "ignore": ["docs/generated/**", "docs/_drafts/**"]
+  },
+  "simplelog": {
+    "root": "docs/logs",
+    "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 `npx -y @simpledoc/simpledoc check` and `npx -y @simpledoc/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 `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.
+
+### simplelog.root
+
+- **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
+
+- **Type:** number
+- **Meaning:** Default threshold (in minutes) for starting a new session section.
+- **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)
+
+`simpledoc.json`
+
+```json
+{
+  "docs": {
+    "root": "docs"
+  },
+  "frontmatter": {
+    "defaults": {
+      "author": "Jane Doe <[email protected]>",
+      "tags": ["docs", "simpledoc"]
+    }
+  },
+  "check": {
+    "ignore": ["docs/generated/**"]
+  },
+  "simplelog": {
+    "root": "docs/logs"
+  }
+}
+```
+
+### Local override (uncommitted)
+
+`.simpledoc.local.json`
+
+```json
+{
+  "docs": {
+    "root": "docs"
+  },
+  "frontmatter": {
+    "defaults": {
+      "author": "Alice Example <[email protected]>"
+    }
+  },
+  "simplelog": {
+    "root": "docs/logs/_local/alice",
+    "thresholdMinutes": 2,
+    "timezone": "Europe/Berlin"
+  }
+}
+```
+
+## 6) Git ignore
+
+Teams SHOULD add `.simpledoc.local.json` to `.gitignore` to prevent accidental commits.

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.

docs/SIMPLELOG_SPEC.md

@@ -0,0 +1,182 @@
+# SimpleLog
+
+> SimpleDoc subspec: 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) Frontmatter (required)
+
+Files MUST start with YAML frontmatter that follows SimpleDoc conventions.
+
+Required fields:
+
+- `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 fields:
+
+- `last_section`: ISO-8601 timestamp with offset (start time of the latest section).
+- `updated`: ISO-8601 timestamp with offset.
+
+Example:
+
+```md
+---
+title: Daily Log 2025-12-01
+author: Jane Doe <[email protected]>
+date: 2025-12-01
+tz: Europe/Berlin
+created: 2025-12-01T00:00:00+01:00
+last_section: 2025-12-01T09:13:00+01:00
+---
+```
+
+Notes:
+
+- The file date is interpreted in the `tz` timezone.
+- DST transitions are supported because each entry includes an offset.
+
+## 4) Session sections (threshold)
+
+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:MM`
+  - `HH` is 24-hour, zero-padded (`00-23`).
+
+Example:
+
+```md
+## 09:13
+
+## 14:03
+```
+
+Rules:
+
+- SHOULD be in chronological order.
+- A section may exist with no entries.
+
+## 5) Entry format (appendable, human-readable, parseable)
+
+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
+Standup notes #team
+
+[WARN] API latency spike service=orders p95_ms=840
+
+09:14:10+01:00 Deployed v1.8.2 #deploy ticket=ABC-123
+```
+
+Multiline entries:
+
+- Continuation lines are allowed and are stored as-is.
+- CLI implementations SHOULD NOT alter indentation; they only ensure a blank line separates entries.
+
+Example:
+
+```md
+Incident review #ops
+
+- suspected cause: cache stampede
+- mitigation: rate-limit + warmup
+```
+
+## 6) Optional full timestamp derivation
+
+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`
+
+Full timestamp:
+
+- `YYYY-MM-DDTHH:MM[:SS]+HH:MM` or `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 (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`.
+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 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).
+
+This guarantees the tool only appends (no in-file insertion) while keeping session grouping.
+
+## 8) Complete example file
+
+`2025-12-01.md`
+
+```md
+---
+title: Daily Log 2025-12-01
+author: Jane Doe <[email protected]>
+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
+
+Checked alerts #ops
+
+[WARN] Elevated error rate service=api code=502
+notes="started after deploy"
+
+## 14:03
+
+Deployed v1.8.2 #deploy ticket=ABC-123
+
+## 14:27
+
+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 frontmatter `tz` as the default.
+- Allow an optional zone ID after the offset if you include a timestamp prefix, e.g. `10:00:00+01:00 Europe/Berlin ...`.