opencode-skills-collection 4.0.0 → 4.0.1

package/bundled-skills/lore/references/platform-mirrors.md

@@ -0,0 +1,377 @@
+# Platform mirrors reference
+
+How `.lore/*` content gets mirrored to platform-specific config files. The main `SKILL.md` covers the high-level rules; this file holds the per-platform mapping, the two-section file structure, and the algorithm that resolves which files to generate (auto-detect by default, explicit override available).
+
+## Platform → file mapping
+
+| Platform | File (default) | Also accepted |
+|---|---|---|
+| Claude Code | `CLAUDE.md` (root) | `.claude/CLAUDE.md` |
+| Cursor | `.cursorrules` (root) | `.cursor/rules/*.mdc` |
+| Cline | `.clinerules` (root) | — |
+| Aider | `AGENTS.md` (root) | `CONVENTIONS.md` |
+| OpenAI Codex | `AGENTS.md` (root) | — |
+| OpenCode | `AGENTS.md` (root) | — |
+| Windsurf | `.windsurfrules` (root) | — |
+| GitHub Copilot | `.github/copilot-instructions.md` | — |
+| Continue.dev | `.continue/rules/lore.md` | — |
+| LangGraph / DeepAgents | (no file — inject at runtime) | — |
+
+For LangGraph and DeepAgents, the skill does not produce a mirror file. Read `.lore/*.md` directly or ingest into the system prompt at runtime — that ingestion is the user's responsibility.
+
+## Resolution: how `mirror_targets` is computed
+
+When the skill needs to know which platform files to generate (during `init`, `mirror`, and `compress` when `auto_mirror: true`), it runs the following procedure:
+
+```
+resolve_mirror_targets(config, repo_root):
+
+    # 1. If config has mirror_targets set, auto-detect is skipped, but validation is not
+    if "mirror_targets" in config:
+        return validate_mirror_targets(config["mirror_targets"], repo_root)
+
+    # 2. Scan repo root for existing platform files (see Scan candidates)
+    detected = scan_existing_platform_files(repo_root)
+    if detected:
+        return validate_mirror_targets(detected, repo_root)
+
+    # 3. Nothing detected → ask user via multi-select, persist to config, return
+    selected = ask_user_multi_select(AGENT_CHOICES)
+    write_mirror_targets_to_config(selected)
+    return validate_mirror_targets(selected, repo_root)
+```
+
+This is the core resolution used by all three commands. `init` extends it with classification and per-file takeover steps — see "Init-time behavior (full procedure)" below.
+
+### Mandatory target validation
+
+Validation is fail-closed and atomic. Validate the complete target list **before reading,
+creating, classifying, archiving, or writing any target**. If one entry fails, report it and
+abort the mirror operation without touching any target.
+
+For each target:
+
+1. Require a non-empty string containing no NUL byte. Reject absolute paths on every
+   platform (POSIX `/...`, Windows drive paths such as `C:\\...`, and UNC paths).
+2. Parse path components without interpreting the value as a shell pattern. Reject any `..`
+   component; normalize `.` and repeated separators only after that rejection.
+3. Require the normalized relative path to match this allowlist exactly:
+   `CLAUDE.md`, `.claude/CLAUDE.md`, `.cursorrules`, `.clinerules`, `AGENTS.md`,
+   `CONVENTIONS.md`, `.windsurfrules`, `.github/copilot-instructions.md`, or
+   `.continue/rules/lore.md`; or match `.cursor/rules/<name>.mdc`, where `<name>` is one
+   non-empty filename segment (no nested directory).
+4. Resolve `repo_root` to its canonical path. Walk every existing component of the target
+   with symlinks resolved and require it to remain inside that canonical root. For a missing
+   target, resolve its nearest existing parent the same way. Reject a target whose file or
+   parent symlink escapes the root. Perform this check again immediately before every read or
+   write to reduce check/use races.
+
+Examples: accept `CLAUDE.md`, `.github/copilot-instructions.md`, and
+`.cursor/rules/lore.mdc`. Reject `/tmp/CLAUDE.md`, `../CLAUDE.md`,
+`.cursor/rules/nested/lore.mdc`, `notes.md`, and an allowlisted-looking path whose existing
+parent or file is a symlink outside the project.
+
+### Scan candidates
+
+The auto-detect step checks for the following paths at `repo_root`:
+
+```
+CLAUDE.md
+.claude/CLAUDE.md
+.cursorrules
+.clinerules
+AGENTS.md
+CONVENTIONS.md
+.windsurfrules
+.github/copilot-instructions.md
+.continue/rules/lore.md
+.cursor/rules/*.mdc        # glob: any .mdc file under .cursor/rules/
+```
+
+These match the platform table above (default + "Also accepted" filenames). The `.cursor/rules/*.mdc` entry is a glob — it's a hit if `.cursor/rules/` exists and contains at least one `.mdc` file.
+
+### Multi-select agent choices
+
+When Step 3 fires, present this question to the user:
+
+| Choice | Primary file written |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Cursor | `.cursorrules` |
+| Cline | `.clinerules` |
+| Aider | `AGENTS.md` |
+| Codex | `AGENTS.md` |
+| OpenCode | `AGENTS.md` |
+| Windsurf | `.windsurfrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Continue.dev | `.continue/rules/lore.md` |
+
+Aider, Codex, and OpenCode all map to `AGENTS.md`. Selecting any combination produces one entry. Selecting nothing is valid — writes `mirror_targets: []` (no mirrors generated).
+
+### When this runs
+
+- `lore init` — always interactive.
+- `lore mirror` when `mirror_targets` is absent — also interactive (skill is invoked through chat).
+- `lore compress` (when `auto_mirror: true`) — also goes through this resolution if `mirror_targets` is absent.
+
+Both paths use the same function. Once `init` has run, `mirror_targets` is set, so subsequent `mirror` calls hit Step 1 and are silent.
+
+## Two-section file structure
+
+Every mirror file is split into two sections by a `---` separator. The top section is Skill-managed and rewritten on mirror regeneration. The bottom section is user-editable and preserved verbatim.
+
+```markdown
+## Lore (auto-managed)
+
+# .lore SUMMARY (synced 2026-07-09)
+
+> Last compressed: 2026-07-09
+> Total entries: 247 across 3 scopes
+
+## Global
+- Monorepo with pnpm workspaces + Turborepo — [_global/ARCHITECTURE.md#ARCH-2026-01-15-d7a3]
+...
+
+---
+
+## My notes (free edit)
+
+- Keep answers concise
+- Currently refactoring the user auth module
+- Prefer English
+```
+
+The `---` separator is a literal Markdown horizontal rule. Both sections are plain Markdown so any agent or editor can render them normally.
+
+### Section detection rules
+
+When syncing a mirror file:
+
+1. If the file contains `---` on its own line, that line is the boundary. Everything above is the Lore section, everything below is My notes.
+2. If the file contains a `## My notes` header, the My notes section starts at that header and goes to EOF.
+3. If neither marker is present, the entire file is treated as the Lore section (i.e. no My notes section). Subsequent sync appends a separator + empty My notes section.
+4. If the file is missing the `## Lore` header but has `## My notes`, the entire file is treated as user notes. Skill does not write to it. User is asked to confirm before sync restructures the file.
+
+## Sync-time behavior
+
+**`sync` does not regenerate platform mirrors.** This is intentional — see the "Mirror update triggers" section in `SKILL.md`. The skill only writes `.lore/*.md` during `sync`. To update mirrors after `sync`, the user runs `lore mirror` (or `compress`, which calls mirror generation as a side effect).
+
+If a project needs the old behavior (mirror updates on every `sync`), set `sync_updates_mirror: true` in `.lore/.config.json`.
+
+## Mirror-time behavior (`lore mirror`)
+
+This is the actual write step for platform mirrors.
+
+1. Validate the complete configured target list using "Mandatory target validation" above.
+   Abort without reading or writing any target if validation fails.
+2. Read the current state of `.lore/SUMMARY.md` and the scope-tagged index.
+3. For each validated mirror target, recheck canonical containment immediately before access,
+   then read the existing file and detect the section boundary.
+4. Compute the new Lore section content.
+5. **Content-based dedup**: if the new Lore section content is byte-identical to the existing one, skip writing. Report "No changes needed: `<file>`".
+6. If different, replace the Lore section (full rewrite, no merge with previous content). Preserve the My notes section verbatim.
+7. Recheck canonical containment, then write the file back. Report "Mirror updated: `<file>`".
+
+The content-based dedup step (4) is the key reason `mirror` can be run frequently without polluting `git log` — most invocations will be no-ops once the mirror is in sync.
+
+## Init-time behavior (full procedure)
+
+The `init` command extends the resolution algorithm above with classification and per-file takeover steps. The full procedure:
+
+1. **Check whether `.lore/` exists.**
+   - Absent → create `.lore/` and write an initial empty config.
+   - Present → load existing `.lore/.config.json` (use defaults if missing).
+
+2. **Scan existing platform files** in repo root using the same candidate list as the resolution algorithm. Result: list of paths that exist.
+
+3. **Classify each detected file** into one of three classes:
+   - **Class (a)** — already a lore mirror: contains `## Lore` section.
+   - **Class (b)** — user-written: contains `## My notes` but no `## Lore`.
+   - **Class (c)** — unmarked: neither header present.
+
+   For class (b) and (c) files, present a per-file choice:
+   - **Take over**: file becomes a two-section mirror; existing content is preserved as My notes.
+   - **Preserve as-is**: file is left alone; NOT added to `mirror_targets`.
+   - **Abort**: exit init entirely. `.lore/` may exist (from Step 1) but no `mirror_targets` is written.
+
+   Class (a) files are auto-included in `mirror_targets`.
+
+4. **Multi-select question.** "Which agents do you use in this project?" Default pre-selection: every agent corresponding to a class (a) file. Empty selection is allowed — but class (a) files still get included via Step 5.
+
+5. **Compute final `mirror_targets`** by combining three sources and deduplicating:
+   - All class (a) files from Step 3 (always included, regardless of Step 4 selection).
+   - Files chosen via "take over" in Step 3.
+   - Primary files for additional agents the user selected in Step 4 that aren't already covered.
+
+   Dedup: Aider and Codex both map to `AGENTS.md` and collapse to one entry.
+
+6. **Write `.lore/.config.json`** with `mirror_targets` populated.
+
+7. **Generate initial mirror files** for each target:
+   - File absent → full template (`## Lore` + `---` + empty `## My notes`).
+   - File present with `## Lore` → refresh Lore section, preserve My notes verbatim.
+   - File present and "take over" chosen → old content becomes My notes, new `## Lore` above.
+   - File present and "preserve" chosen → no write.
+
+For each generated mirror file, the section template is:
+
+```
+## Lore (auto-managed)
+
+<initial or refreshed Lore content>
+
+---
+
+## My notes (free edit)
+
+<preserved or empty>
+```
+
+## What gets mirrored
+
+The mirror's Lore section is an **index** into `.lore/` — not a copy of its content. This keeps per-session token cost flat (~500 B regardless of project size) and aligns with how platform instruction files (`CLAUDE.md`, `.cursorrules`, etc.) are designed to be used: as small pointers that tell the agent where to find detail on demand.
+
+The agent generating the mirror walks `.lore/` and emits the structure below. Sections appear only when their content exists (adaptive rendering).
+
+### Index template
+
+```
+## Lore (auto-managed)
+
+Project memory. Read deeper on demand.
+
+**Structure**:
+- Digest: `.lore/SUMMARY.md` (top-level overview)
+- Global: `.lore/_global/` (architecture, decisions, conventions)
+- Scopes: `.lore/scopes/`
+  - `.lore/scopes/<scope_name>/` (<description>)
+  - `.lore/scopes/<scope_name>/`
+  ...
+
+**Query**: `lore query <term>` or `lore query <scope>:<term>`
+**Update**: see the `lore` skill (init / sync / query / audit / compress / mirror)
+
+---
+## My notes (free edit)
+```
+
+The `## Lore (auto-managed)` opener, `---` separator, and `## My notes (free edit)` closer are **always present** — only the `**Structure**:` body varies with adaptive rendering. Agent preserves the My notes section verbatim across regenerations.
+
+### Field sources
+
+- `<scope_name>` — directory name under `.lore/scopes/`. Each scope's full path is `.lore/scopes/<scope_name>/`.
+- `<description>` — extracted from `.lore/scopes/<scope_name>/ARCHITECTURE.md` via the HTML comment `<!-- description: ... -->`. See "Scope description extraction" below. If absent, the description is omitted (scope row still appears, just without parenthetical).
+
+The index does **not** track the project's source-directory mapping for each scope (e.g. `packages/frontend/` for the `frontend` scope). Source paths are detected by `references/monorepo-detection.md` at init time but not persisted in `.lore/`. If a user needs source paths surfaced in the mirror, that mapping belongs in the project's own docs.
+
+### Section visibility rules
+
+| Section | Visible when |
+|---|---|
+| `Digest:` line | always |
+| `Global:` line | `.lore/_global/` exists and has any entry |
+| `Scopes:` block | at least one scope directory exists under `.lore/` |
+| `Query:` line | always |
+| `Update:` line | always |
+
+### Adaptive renderings
+
+Only the `**Structure**:` body varies. The `## Lore (auto-managed)` opener, `---` separator, and `## My notes (free edit)` closer are always present and unchanged.
+
+**Empty project** (just initialized, no entries yet):
+
+```
+## Lore (auto-managed)
+
+Project memory. Read deeper on demand.
+
+**Structure**:
+- Digest: `.lore/SUMMARY.md` (top-level overview)
+
+**Query**: `lore query <term>`
+**Update**: see the `lore` skill
+
+---
+## My notes (free edit)
+```
+
+`Global:` and `Scopes:` blocks omitted.
+
+**Single-scope project**:
+
+```
+**Structure**:
+- Digest: `.lore/SUMMARY.md`
+- Global: `.lore/_global/`
+- Scopes: `.lore/scopes/`
+  - `.lore/scopes/frontend/` (React 18 + TypeScript)
+```
+
+`Scopes:` block has one entry.
+
+**Monorepo with multiple scopes**:
+
+```
+**Structure**:
+- Digest: `.lore/SUMMARY.md`
+- Global: `.lore/_global/`
+- Scopes: `.lore/scopes/`
+  - `.lore/scopes/frontend/` (React 18 + TypeScript)
+  - `.lore/scopes/backend/` (PostgreSQL + Prisma)
+  - `.lore/scopes/shared/`
+```
+
+### Scope description extraction
+
+The agent scans `.lore/scopes/<scope_name>/ARCHITECTURE.md` for the **first line matching** `<!-- description: <text> -->` (anchored to start of line; `description:` literal). Rules:
+
+- **First match wins.** If multiple `<!-- description: ... -->` lines exist, only the first is used.
+- **`<text>` is single-line.** A comment must not contain a newline before `-->`. Multi-line comments are ignored.
+- **Whitespace trimmed.** Leading and trailing whitespace inside `<text>` is stripped.
+- **No match → no description.** The scope row appears without parenthetical; the row is not removed.
+
+Example `ARCHITECTURE.md` with description:
+
+```
+<!-- description: React 18 + TypeScript frontend -->
+# Frontend Architecture
+
+All UI code lives here. ...
+```
+
+### Scope ordering
+
+Scope rows in the `Scopes:` block are emitted in **alphabetical order** by `<scope_name>`. Pinning order is important: the content-based dedup step compares byte-for-byte, so any order change between runs causes spurious "Mirror updated" reports.
+
+### What does NOT trigger mirror regeneration
+
+Index content does not change when:
+- Individual entries are edited
+- `SUMMARY.md` content is updated (the index only points to its path)
+- Entry counts change
+- A scope's `ARCHITECTURE.md` content changes (only the `<!-- description: -->` comment affects the index)
+
+Index content changes require regeneration when:
+- A new scope directory is added under `.lore/`
+- A scope is removed
+- A scope's `ARCHITECTURE.md` `<!-- description: -->` line changes
+- `.lore/_global/` gains or loses its first entry (Global section visibility flips)
+
+## Manual operations
+
+| Command | Effect |
+|---|---|
+| `lore mirror` | Force-regenerate all configured platform mirrors from current `.lore/*` state. Content-based dedup: skips targets whose new Lore section matches the existing one. |
+| `lore mirror reset <file>` | Archive current My notes content to `.lore/.archive/<file>-<date>.md`, then write a clean mirror with only the Lore section. User must confirm. |
+| `lore mirror show <file>` | Print the file with the two sections clearly delimited in the output. Pure read. |
+| `lore mirror check` | For each configured target, verify it has a `---` separator and a `## My notes` section. Report any structural problems. Read-only. |
+
+## Trigger rules
+
+| Trigger | Behavior |
+|---|---|
+| `init` confirms draft | Auto-generate mirrors for all configured targets using the init-time rules above. |
+| `sync` proposal accepted | Writes to `.lore/*.md` only. Does **not** touch mirrors. User runs `lore mirror` separately to publish. (Override: set `sync_updates_mirror: true` in config to restore old behavior.) |
+| `compress` completes | If `auto_mirror: true`, regenerate mirrors (with content-based dedup). Otherwise ask per target. |
+| `lore mirror` | Force-regenerate all configured targets with content-based dedup. |
+| `query` / `audit` | Never touches mirrors. |

package/bundled-skills/lore/references/stale-new-markers.md

@@ -0,0 +1,62 @@
+# Stale / New marking convention
+
+When `sync` proposes a change, it never silently mutates files. Instead it emits one or more of these markers. The user reads the proposal and accepts/rejects per marker type.
+
+## Marker types
+
+| Marker | Purpose |
+|---|---|
+| `[NEW]` | Propose adding a new entry |
+| `[STALE]` | Propose marking an existing entry as superseded/contradicted |
+| `[REFINED]` | Propose updating an existing entry's text in place |
+| `[ALERT]` | Conflicting signal detected during sync that needs human resolution |
+| `[COMPRESS NOTICE]` | Threshold tripped; suggest running `compress` after this sync |
+
+## Full example
+
+```markdown
+## [NEW] Proposed additions
+- [scopes/frontend/ARCHITECTURE.md] [ARCH-2026-07-09-b4d2] Use `react-hook-form` for all forms. #added:2026-07-09
+- [scopes/frontend/CONVENTIONS.md] [CONV-2026-07-09-c5e1] Never use `any` in TypeScript; prefer `unknown` + narrowing. #added:2026-07-09
+
+## [STALE] Candidates for archive
+- [scopes/frontend/ARCHITECTURE.md] [ARCH-2026-01-15-d7a3] Use Pages Router (Next.js). #stale:2026-07-09
+  Evidence: `frontend/package.json` shows `"next": "^14.0.0"` with `app/` directory present.
+
+## [REFINED] Existing entries updated
+- [scopes/frontend/DECISIONS.md] [DEC-2026-02-03-7c19] (was: "use Zustand") → "use Zustand v4+ with slices pattern" #verified:2026-07-09
+
+## [ALERT] Conflicting signals detected during sync
+- Sync proposes `[CONV-2026-07-09-c5e1]` (no `any`), but `[CONV-2026-06-01-f0a1]` already says "use `any` sparingly in test mocks". Resolution: refined entry above clarifies the exception.
+
+## [COMPRESS NOTICE]
+- Memory bank has 612 entries; last compression 47 days ago. Consider running `lore compress` after this sync.
+```
+
+## User reply semantics
+
+The user can reply with:
+
+- `"accept all"` — apply every `[NEW]`, `[STALE]`, and `[REFINED]` in the proposal
+- `"accept only NEW"` — add new entries, leave existing untouched
+- `"accept NEW + REFINE"` — add new and refine, do not mark anything stale
+- `"drop STALE #d7a3"` — skip one specific stale entry
+- `"reject all"` — discard the entire proposal
+
+For partial acceptance, the user should explicitly list which items to apply.
+
+## Marker → file operation mapping
+
+| Marker | File action |
+|---|---|
+| `[NEW]` | Append a new bullet to the named file, with `#added:<today>` |
+| `[STALE]` | Append `#stale:<today>` tag to the existing entry; entry stays in the file |
+| `[REFINED]` | Replace the entry text in place, keep the ID, update `#verified:<today>` |
+| `[ALERT]` | No direct file change; only marks the conflict for user resolution |
+| `[COMPRESS NOTICE]` | No file change; advisory only |
+
+Note: `[STALE]` does not delete or move anything. The entry remains in its file with a `#stale` tag until the user (or a later sync) explicitly moves it to `archive/`. This keeps the rollback path clean.
+
+## When audit uses these markers
+
+`audit` does **not** use these markers. It writes its own severity tags (`[CONFLICT]`, `[STALE]`, `[UNVERIFIED]`) into the audit report file under `.lore/audit/`. The naming overlap (`[STALE]` in sync vs `[STALE]` severity in audit) is intentional — both refer to the same concept (entry no longer accurate) but operate in different files with different downstream actions.

package/bundled-skills/lore/references/summary-template.md

@@ -0,0 +1,98 @@
+# SUMMARY.md template
+
+`compress` generates/refreshes `SUMMARY.md` from existing entries. This file holds the schema and worked example.
+
+## Skeleton
+
+```markdown
+# .lore SUMMARY
+
+> Last compressed: <YYYY-MM-DD>
+> Total entries: <N> across <M> scopes
+
+## Global (`_global/`)
+
+### Architecture
+- <bullet> — [_global/ARCHITECTURE.md#<ID>]
+- ...
+
+### Decisions
+- ...
+
+### Conventions
+- ...
+
+## Scope: <name>
+
+### Architecture
+- ...
+
+### Decisions
+- ...
+
+### Conventions
+- ...
+
+## Scope: <name2>
+...
+```
+
+## Selection rule (3–5 entries per scope per layer)
+
+For each (scope, layer) tuple, pick entries by this priority:
+
+1. Most recent `#verified` date wins
+2. Tiebreaker: most recent `#added` date
+3. Tiebreaker: entries that contain "primary" / "main" / "core" / "use <X>" — these are typically the anchor facts
+
+If a (scope, layer) has fewer than 3 entries, include all of them.
+
+If a (scope, layer) is empty, omit the subsection entirely.
+
+## Worked example
+
+```markdown
+# .lore SUMMARY
+
+> Last compressed: 2026-07-09
+> Total entries: 247 across 3 scopes
+
+## Global (`_global/`)
+
+### Architecture
+- Monorepo with pnpm workspaces + Turborepo — [_global/ARCHITECTURE.md#ARCH-2026-01-15-d7a3]
+- Node.js 20 baseline — [_global/ARCHITECTURE.md#ARCH-2026-02-01-9b1c]
+
+### Decisions
+- Rejected Nx → chose Turborepo (faster builds, simpler config) — [_global/DECISIONS.md#DEC-2026-02-03-7c19]
+
+### Conventions
+- All packages use TypeScript strict mode — [_global/CONVENTIONS.md#CONV-2026-01-20-b1e8]
+
+## Scope: frontend
+
+### Architecture
+- Next.js 14 App Router — [scopes/frontend/ARCHITECTURE.md#ARCH-2026-03-10-a1b2]
+- TanStack Query for server state — [scopes/frontend/ARCHITECTURE.md#ARCH-2026-03-15-e5f6]
+
+### Decisions
+- Zustand over Redux (60% less boilerplate) — [scopes/frontend/DECISIONS.md#DEC-2026-02-03-7c19]
+
+### Conventions
+- No default exports — [scopes/frontend/CONVENTIONS.md#CONV-2026-04-12-c3d4]
+
+## Scope: backend
+
+### Architecture
+- Node.js + Fastify + PostgreSQL — [scopes/backend/ARCHITECTURE.md#ARCH-2026-01-15-e5f6]
+
+### Decisions
+- Fastify over Express (3x throughput in our benchmarks) — [scopes/backend/DECISIONS.md#DEC-2026-02-10-a8c9]
+
+### Conventions
+- All DB queries go through repository pattern — [scopes/backend/CONVENTIONS.md#CONV-2026-03-01-b1d2]
+```
+
+## Idempotency
+
+Running `compress` twice without intervening `sync`s produces identical content (modulo the `Last compressed:` date). This is intentional — compress is a pure projection of the underlying entries.

package/bundled-skills/lore/scripts/README.md

@@ -0,0 +1,54 @@
+# lore scripts
+
+Cross-platform Python 3.6+ helpers that reduce repetitive mechanical work. No third-party dependencies. Called by `init` / `sync` / `audit` / `compress` / `lore mirror`; can also be run standalone for ad-hoc inspection.
+
+The script list and quick-reference command examples live in the project root `README.md` "Scripts" section. This file covers the things that don't fit there: design intent, integration points, and limits.
+
+## Design notes
+
+**Cross-platform first.** Python standard library only. No `bash`, no `jq`, no platform-specific tools. The same invocation works on Windows, Linux, macOS.
+
+**JSON-friendly output.** Every script supports `--json` for machine consumption. Agent callers parse the output; humans pipe to `less` or `jq` (if available).
+
+**Composition.** `find_duplicates.py` and `find_stale.py` shell out to `list_entries.py --json` rather than re-implementing the parser. One source of truth for entry format — if the format ever changes, only `list_entries.py` needs updating.
+
+**Read-only by default.** None of these scripts write to `.lore/`. They observe; the agent decides what to do with findings.
+
+**Run from project root.** `list_entries.py` walks up the directory tree looking for `.lore/`. The other scripts depend on it via subprocess, so the same constraint applies transitively.
+
+## When each script is called
+
+| Script | Call site | Purpose |
+|---|---|---|
+| `history.py` | lore history | List git commits related to a memory entry / file / scope |
+| `id_hash.py` | Any time a new entry is written (init / sync) | Compute the 4-char content hash for the entry ID |
+| `list_entries.py` | Pre-step of query / audit / compress | Enumerate all entries as JSON for downstream processing |
+| `find_duplicates.py` | sync step 5 (de-duplication) | Identify candidate duplicate entries before writing |
+| `find_stale.py` | audit step 2; compress step 2; lore mirror (optional) | Identify entries past the verified-date threshold or already marked `#stale` |
+
+## Output channels
+
+**stdout is the data channel; stderr is the warning channel.** All scripts follow this split so `--json` consumers never have to filter noise out of their parsers. Currently `list_entries.py` is the only script that emits a warning:
+
+- `[WARN] .lore/.config.json has no schema_version field.` — fires once per invocation when the config file exists but lacks the version field. Add `"schema_version": 1` to silence it.
+- `[WARN] .lore/.config.json#schema_version=N is newer than this lore skill expects (max: 1).` — fires when the config version exceeds what this skill understands. Pull the latest lore from upstream.
+
+Both warnings are informational; `list_entries.py` always produces the same stdout regardless of config state. See `references/compatibility.md` for the full schema versioning policy.
+
+## Testing
+
+Without a real `.lore/`, you can sanity-check that imports and argument parsing work:
+
+```bash
+python scripts/id_hash.py "test entry"
+python scripts/list_entries.py   # should print "(no entries)" or exit with a clear error
+```
+
+`list_entries.py`, `find_duplicates.py`, and `find_stale.py` require a populated `.lore/` to produce meaningful output. Set one up via `lore init` first.
+
+## Limitations
+
+- **Token-overlap dedup, not semantic.** Jaccard similarity catches rewrites with similar words but misses semantic equivalence (e.g. "use TypeScript" vs "TypeScript-only codebase"). Deeper checks still need an LLM pass.
+- **Naive date math.** `find_stale.py` uses wall-clock dates from `#verified` / `#added` tags. If the system's clock is wrong, results will be off.
+- **No automatic archive promotion.** The script reports pending-archive entries but does not move them. Use `lore sync` to actually relocate to `.lore/archive/`.
+- **Hash collisions on identical text are theoretically possible** (4 hex chars = 16 bits = 1 in 65536). In practice a lore project will not hit this. If it does, slightly edit the entry text to bump the hash.

package/bundled-skills/lore/scripts/README.zh-CN.md

@@ -0,0 +1,54 @@
+# lore 脚本
+
+跨平台 Python 3.6+ 辅助脚本，减少重复的机械工作。无第三方依赖。被 `init` / `sync` / `audit` / `compress` / `lore mirror` 调用，也可独立运行做临时检查。
+
+脚本清单和命令速查在仓库根 `README.md` 的"Scripts"章节里。本文件覆盖根 README 不适合放的内容：设计意图、集成点、局限。
+
+## 设计要点
+
+**优先跨平台。** 仅使用 Python 标准库，不依赖 `bash`、`jq` 或任何平台特定工具。Windows / Linux / macOS 行为完全一致。
+
+**JSON 友好输出。** 每个脚本都支持 `--json` 便于机器消费。Agent 调用方解析输出；人类可以直接 `less` 或 `jq`（如果装了）。
+
+**组合而非重复。** `find_duplicates.py` 和 `find_stale.py` 通过 `list_entries.py --json` 复用解析器，不重复实现 entry 格式解析。Entry 格式只在一处定义——将来格式变更只需改 `list_entries.py`。
+
+**默认只读。** 这些脚本不写 `.lore/`，只观察。Agent 决定如何处理发现的问题。
+
+**从项目根目录运行。** `list_entries.py` 向上遍历定位 `.lore/`。其他脚本通过 subprocess 调用它，所以这个约束会传递生效。
+
+## 何时调用
+
+| 脚本 | 调用点 | 用途 |
+|---|---|---|
+| `history.py` | lore history | 列出与 memory entry / file / scope 相关的 git commits |
+| `id_hash.py` | 写新 entry 时（init / sync）| 计算 entry ID 的 4 字符内容 hash |
+| `list_entries.py` | query / audit / compress 的预步骤 | 把所有 entry 枚举为 JSON 供后续处理 |
+| `find_duplicates.py` | sync 步骤 5（去重）| 写之前找出可能的重复 entry |
+| `find_stale.py` | audit 步骤 2；compress 步骤 2；lore mirror（可选）| 找出过期 entry 或已标记 `#stale` 的 entry |
+
+## 输出通道
+
+**stdout 是数据通道；stderr 是警告通道。** 所有脚本遵循这个分离，这样 `--json` 消费者就不必从解析结果里过滤噪音。当前只有 `list_entries.py` 会发警告：
+
+- `[WARN] .lore/.config.json has no schema_version field.` —— 配置文件存在但缺 `schema_version` 字段时，每个调用触发一次。加 `"schema_version": 1` 即可消除。
+- `[WARN] .lore/.config.json#schema_version=N is newer than this lore skill expects (max: 1).` —— 配置版本超过本 skill 能理解的范围时触发。从上游 pull 最新 lore。
+
+两条警告都是告知性质；`list_entries.py` 不管配置状态如何，stdout 输出始终一致。完整 schema 版本策略见 `references/compatibility.md`。
+
+## 测试
+
+没有真实 `.lore/` 时，可以快速验证 import 和参数解析是否正常：
+
+```bash
+python scripts/id_hash.py "test entry"
+python scripts/list_entries.py   # 应输出 "(no entries)" 或清晰报错
+```
+
+`list_entries.py`、`find_duplicates.py`、`find_stale.py` 需要有内容的 `.lore/` 才能产出有意义的输出。先用 `lore init` 建一个。
+
+## 局限
+
+- **去重只到词袋重叠程度。** Jaccard 相似度能抓到词汇相似的改写，但抓不到语义等价（如 "use TypeScript" vs "TypeScript-only codebase"）。更深的检查仍需 LLM 介入。
+- **日期计算比较朴素。** `find_stale.py` 直接用 `#verified` / `#added` 标签的日期。如果系统时钟不对，结果会偏差。
+- **不自动 archive。** 脚本会报告待 archive 的 entry，但不会移动它们。实际搬迁到 `.lore/archive/` 仍需通过 `lore sync` 完成。
+- **理论上可能有 hash 冲突**（4 个十六进制字符 = 16 位 = 1/65536 概率）。实际项目基本不会遇到。如果遇到了，对 entry 文本做微调以改变 hash。