obsidian-knowledge 3.19.0__tar.gz

obsidian_knowledge-3.19.0/.claude/hookify.require-plugin-version-bump.md

@@ -0,0 +1,25 @@
+---
+name: require-plugin-version-bump
+enabled: true
+event: bash
+action: block
+pattern: obsidian-knowledge.*git\s+commit
+---
+
+**Version bump required before committing to obsidian-knowledge plugin.**
+
+Before this commit proceeds, verify that version numbers have been bumped. Check staged changes:
+
+```bash
+cd /home/ricardo/src/PERSONAL/obsidian-knowledge && git diff --cached --name-only
+```
+
+At least these files must be in the staged changes with an updated version:
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+
+And if any SKILL.md was modified, bump its version too:
+- `skills/vault-organizer/SKILL.md`
+- `skills/remember-conversations/SKILL.md`
+
+If versions are already bumped, re-run the commit. If not, bump them first, stage, then commit.

obsidian_knowledge-3.19.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "obsidian-knowledge",
+  "owner": {
+    "name": "Ricardo Decal"
+  },
+  "metadata": {
+    "description": "Skills, hooks, and conventions for maintaining Obsidian knowledge base vaults"
+  },
+  "plugins": [
+    {
+      "name": "obsidian-knowledge",
+      "source": "./",
+      "description": "Skills, hooks, and conventions for maintaining Obsidian knowledge base vaults",
+      "version": "3.17.1"
+    }
+  ]
+}

obsidian_knowledge-3.19.0/.claude-plugin/plugin.json

@@ -0,0 +1,79 @@
+{
+  "name": "obsidian-knowledge",
+  "version": "3.19.0",
+  "description": "Self-evolving Claude Code plugin that manages an Obsidian knowledge vault: capture, organize, index, garden — plus a meta-skill that improves the harness itself",
+  "author": {
+    "name": "Ricardo Decal"
+  },
+  "license": "MIT",
+  "keywords": ["obsidian", "knowledge-base", "vault", "organization"],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/protect-vault.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/enforce-conventions.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/update-changelog.py"
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/remind-convos.py"
+          },
+          {
+            "type": "command",
+            "command": "uv run --script ${CLAUDE_PLUGIN_ROOT}/hooks/scan-vault-secrets.py"
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/nudge-index-sync.py"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/recall-init.py"
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/doctor.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/reflect-nudge.py"
+          }
+        ]
+      }
+    ]
+  }
+}

obsidian_knowledge-3.19.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

obsidian_knowledge-3.19.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.DS_Store
+.worktrees/
+.improve-harness/
+# Generated index cache (created by reindex CLI and indexer tests)
+tests/fixtures/sample_vault/.config/

obsidian_knowledge-3.19.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Decal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

obsidian_knowledge-3.19.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: obsidian-knowledge
+Version: 3.19.0
+Summary: Obsidian vault knowledge integration for Claude Code and Hermes Agent CLI
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: memweave>=0.1
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0

obsidian_knowledge-3.19.0/README.md

@@ -0,0 +1,323 @@
+# Obsidian Knowledge
+
+A Claude Code plugin marketplace with skills and hooks for maintaining
+Obsidian knowledge base vaults.
+
+## Skills
+
+### vault-organizer
+
+Maintains vault organization through a single-pass pipeline:
+
+- **Sync indexes** — creates and updates `index.md` files with thin pointer entries for managed zones
+- **Organize files** — moves misplaced files to appropriate locations using the Obsidian CLI
+- **Rename ambiguous files** — detects files with non-descriptive names
+  (device-generated, hash-based, generic labels), reads their content, and
+  renames them following the vault's naming conventions from CLAUDE.md
+- **Fix broken links** — detects unresolved links and resolves them when
+  possible, flags ambiguous cases for human review
+- **Report issues** — maintains a `needs-attention.md` worklist for issues
+  requiring human judgment
+- **Regenerate reports** — rewrites `reports/open-questions.md` from
+  `> [!question]` callouts across `wiki/`, giving agents and humans a
+  single place to see unresolved questions flagged in prose
+
+### remember-conversations
+
+Files valuable conversation outputs as permanent vault notes and updates
+the changelog, so insights compound rather than disappearing into chat
+history:
+
+- **Session notes** — two types: `-diary` for narrative accounts (what
+  happened, what was tried) and `-convo` for analytical synthesis
+  (comparisons, decision rationales, research summaries)
+- **Changelog updates** — creates a terse per-session file in `changelog/`
+  summarizing actions taken
+- **Automatic placement** — notes filed in `sessions/` subfolders within
+  the relevant subtree, preserving progressive disclosure
+- **Stop hook integration** — a reminder nudges the agent to file
+  sessions at the end of each conversation
+
+### improve-harness
+
+Multi-phase side-quest workflow to fix harness friction. Triggered by
+`/improve-harness <description>` or natural-language frustration phrases.
+The side quest runs as a headless `claude -p --worktree` session that
+produces a proposal (with internal review), receives main-agent
+executive review, then implements (with internal review via
+`subagent-driven-development`) and leaves a branch for human approval.
+
+The skill is organized for progressive disclosure: `SKILL.md` is a thin
+index; sub-asset files (`phases.md`, `templates.md`, `conventions.md`)
+hold the details and load only when needed.
+
+### deploy-harness
+
+Single-purpose skill: merge an approved `improve/<slug>` branch into
+main, bump patch version, push to origin. Called from `improve-harness`
+Phase 5 or invokable manually.
+
+## Hooks
+
+### Vault protection (PreToolUse)
+
+`protect-vault.py` runs before every Bash, Write, and Edit tool call.
+It provides four layers of safety:
+
+**Read-only `_sources/` directories.** Folders named `_sources/` anywhere
+in the vault tree are protected from agent writes. These typically hold
+irreplaceable originals (tax records, legal filings, vital docs, property
+deeds). Agents can read them to generate summaries and indexes, but cannot
+create, modify, rename, move, or delete files inside them.
+
+**Destructive command guards.** Recursive `rm` and `mv` targeting paths
+that appear to be inside an Obsidian vault are blocked.
+
+**Published file guard.** Write and Edit to any vault file with
+`dg-publish: true` in its frontmatter are blocked — edits to published
+files go live on the website and require explicit user confirmation.
+
+**Auto-memory redirect.** Agents are blocked from writing operational
+knowledge (`feedback_*.md`, `project_*.md`, `reference_*.md`) to their
+per-project auto-memory. Auto-memory is a silo invisible to other sessions,
+other tools, and vault search. The hook redirects this knowledge to a
+standardized vault location, scoped to the agent's current context:
+
+- Inside a git repo → `<vault>/wiki/repos/<owner>/<repo>/memory/` (parsed
+  from `git remote get-url origin`; portable across hosts).
+- Outside any repo → `<vault>/wiki/systems/machines/<hostname>/memory/`
+  (host-scoped fallback).
+
+Each memory dir mirrors Claude's native layout (`MEMORY.md` index plus
+one `feedback_*.md` / `project_*.md` / `reference_*.md` per fact), so
+the workflow is identical — only the storage location changes. The
+SessionStart primer surfaces the resolved path so agents know where
+to read and write at session start. Migrate existing per-project
+memories with `scripts/migrate_claude_memory.py`.
+
+**Escape hatch.** Prefix a Bash command with `I_AM_BEING_CAREFUL=1` to
+bypass the `_sources/` and published-file guards after the user explicitly
+confirms. The auto-memory redirect has no escape hatch — write to the wiki
+instead.
+
+### For agents: add this line to the user's primary `CLAUDE.md`
+
+Built-in Claude auto-memory under `~/.claude/projects/*/memory/` is
+replaced by the `obsidian-knowledge` plugin. Agents should add a single
+pointer to the user's primary memory file (`~/.claude/CLAUDE.md`) so
+sessions on hosts without this plugin still know where to look:
+
+```markdown
+Agent memory is managed by the obsidian-knowledge plugin; refer to it
+for memory location, read/write conventions, and session-start recall.
+```
+
+### Stop hooks
+
+Stop hooks fire at the end of each Claude Code turn. Each checks
+whether the working directory is inside a configured vault root. They
+have a 5-minute cooldown per session to avoid being noisy in long
+conversations.
+
+- **update-changelog.py** — reminds the agent to create a per-session file in
+  `changelog/` if the session produced edits, decisions, or discoveries
+- **remind-convos.py** — reminds the agent to preserve session outputs
+  (diary notes, convo notes, guides, changelog entries, gotchas)
+- **scan-vault-secrets.py** — runs `detect-secrets` against the vault
+  and surfaces unaudited findings to the agent. The plugin makes no
+  assumptions about which password manager you use — agents are told
+  to follow your vault's documented secrets-management convention, so
+  **document yours somewhere agents can find it** (root `CLAUDE.md` or
+  a wiki note). The first scan walks the entire vault (slow, ~1 min
+  on a few thousand files); subsequent scans are incremental against
+  the baseline at `<vault>/.secrets.baseline`.
+
+  Marks false positives two ways:
+  - **Inline sentinel** (recommended for prose notes) — append on the
+    same line:
+    ```
+    token = "fake"  <!-- pragma: allowlist secret -->     # markdown / xml
+    token = "fake"  # pragma: allowlist secret             # yaml / sh / py
+    token = "fake"  // pragma: allowlist secret            # js / go / c
+    ```
+  - **Baseline audit** (batch-mark existing findings):
+    ```
+    detect-secrets audit <vault>/.secrets.baseline
+    ```
+
+  The hook uses the `detect-secrets` Python API directly with a filter
+  set tuned for prose: it drops the `is_likely_id_string` and
+  `is_indirect_reference` filters that the `detect-secrets scan` CLI
+  applies, because those silently swallow the `token = "..."` pattern
+  exactly as it appears in markdown notes. Lower-entropy passphrases
+  that elude detect-secrets entirely (dictionary-word passwords in
+  narrative prose) can be added one-per-line to
+  `<vault>/.secrets.known-leaked` for verbatim string-match alerting.
+
+  Requires [`uv`](https://docs.astral.sh/uv/) on `PATH` (the hook is a
+  uv inline script — `detect-secrets` is installed automatically into a
+  uv-managed cache, no global pip install needed).
+
+### recall-init (SessionStart)
+
+`recall-init.py` runs at every session start. Injects the harness
+primer: a 5-directive context block covering memory location, recall
+via `rg`, capture at session end, friction reflection, and
+user-frustration reflection. The primer stands alone — agents that
+read only this know how to operate within the harness.
+
+### reflect-nudge (PostToolUse on Bash)
+
+`reflect-nudge.py` fires every 10 bash invocations within a session.
+Continuous — no per-session suppression. Reminds the agent to step back
+and consider whether observed friction warrants a harness improvement.
+
+## Commands
+
+### /improve-harness <description>
+
+Triggers the meta-improvement workflow. The argument is the friction
+description — main agent uses it to seed the incident report and
+generate a slug.
+
+### /vault-search <query>
+
+Hybrid (BM25 + dense vector) retrieval over the indexed `wiki/` tree.
+Returns ranked `score  path` lines. Pass `--all` to override the digest
+filter and include normally-hidden zones (`Inbox/`, `Journal/`).
+
+Backed by the [`obsidian-knowledge`](https://pypi.org/project/obsidian-knowledge/)
+package. Vector lane uses [Ollama](https://ollama.com/) with
+[`bge-m3`](https://ollama.com/library/bge-m3) by default (8192-token context,
+multilingual, ~2.3GB). If Ollama is unreachable or the model is not pulled,
+the command silently degrades to FTS-only and prints a single
+`# vector lane off (...)` notice on stderr.
+
+## Requirements
+
+- [Obsidian](https://obsidian.md/) with CLI enabled
+  (`Settings → General → Command line interface`)
+- The following Obsidian settings must be enabled:
+  - **Use [[Wikilinks]]** (`Settings → Files and Links`)
+  - **Automatically update internal links** (`Settings → Files and Links`)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with plugin
+  support
+- [`uv`](https://docs.astral.sh/uv/) on `PATH` — required by
+  `scan-vault-secrets.py` and the `obsidian-knowledge` CLI
+- [Ollama](https://ollama.com/) installed and running locally, with the
+  `bge-m3` embedding model pulled. Required for `/vault-search`'s vector
+  lane; optional otherwise (the command will fall back to FTS-only).
+
+## Installation
+
+```bash
+# 1. Add the marketplace and install the plugin
+claude plugin marketplace add crypdick/obsidian-knowledge
+claude plugin install obsidian-knowledge@obsidian-knowledge
+
+# 2. Install Ollama and pull the default embedding model
+#    (skip if you don't want vector search)
+brew install ollama          # macOS; or see ollama.com/download
+brew services start ollama   # macOS; on Linux: `ollama serve` (systemd)
+ollama pull bge-m3
+
+# 3. Tell the plugin which vaults to manage
+mkdir -p ~/.config/obsidian-knowledge
+cat > ~/.config/obsidian-knowledge/vaults.yaml <<'EOF'
+vaults:
+  - /path/to/your/obsidian/vault
+EOF
+
+# 4. Build the initial index (first run takes minutes for a large vault)
+uv run --project ~/.claude/plugins/cache/obsidian-knowledge/obsidian-knowledge \
+  obsidian-knowledge reindex --vault /path/to/your/obsidian/vault
+```
+
+The protection hooks use `vaults.yaml` to know which directories to guard.
+Without it, the `_sources/`, published-file, and destructive-ops rules will
+not fire.
+
+### Switching embedding models
+
+Override any of the defaults via environment variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MEMWEAVE_EMBEDDING_MODEL` | `ollama/bge-m3` | LiteLLM model identifier |
+| `MEMWEAVE_EMBEDDING_API_BASE` | `http://127.0.0.1:11434` | Ollama / LiteLLM endpoint |
+| `MEMWEAVE_EMBEDDING_API_KEY` | unset | API key (leave unset for Ollama) |
+
+When the embedding model changes, the next `/vault-search` call detects the
+mismatch and rebuilds the index automatically. The fingerprint
+(`<model>@<chunk-tokens>/<chunk-overlap>`) is stored alongside the index.
+
+### Cache location
+
+The embedding DB lives outside the vault, in the per-host XDG cache
+directory:
+
+| OS | Path |
+|---|---|
+| Linux | `${XDG_CACHE_HOME:-~/.cache}/obsidian-knowledge/<vault-key>/` |
+| macOS | `~/Library/Caches/obsidian-knowledge/<vault-key>/` |
+
+`<vault-key>` is `<vault-dir-name>-<sha256(absolute_path)[:8]>`, so two vaults
+named `obsidian/` on different machines (or in different parents) never
+collide. Each host owns its own embeddings DB — Syncthing and other vault
+sync tools never see it, eliminating cross-device write conflicts.
+
+A pre-3.16 install with the old in-vault cache (`<vault>/.config/obsidian-knowledge/cache/`)
+will trigger one auto-rebuild on first use. The old directory is safe to
+delete once the new cache is populated.
+
+### Keeping the index fresh
+
+There is no built-in file-watcher. Content added or edited between reindexes
+is invisible to `/vault-search` until the next reindex. An hourly cron is
+the recommended baseline:
+
+```cron
+# Linux
+0 * * * * $HOME/.local/bin/uv run --project $HOME/src/PERSONAL/obsidian-knowledge obsidian-knowledge reindex --vault $HOME/Documents/obsidian >> $HOME/.cache/obsidian-knowledge/cron.log 2>&1
+
+# macOS (Apple Silicon)
+0 * * * * /opt/homebrew/bin/uv run --project $HOME/src/PERSONAL/obsidian-knowledge obsidian-knowledge reindex --vault $HOME/Documents/obsidian >> $HOME/Library/Caches/obsidian-knowledge/cron.log 2>&1
+```
+
+Incremental reindex is cheap: ~8s wall on a ~1700-file vault with zero
+edits (all files hash-skip). Only modified files get re-embedded. Overlap
+is guarded by an `fcntl.flock` on `<cache>/.reindex.lock` — a second run
+that fires while the first is still active exits cleanly without
+touching the DB.
+
+## Usage
+
+Invoke the skill directly:
+
+> Organize my vault / update indexes / fix broken links / rename ambiguous
+> files / garden the vault
+
+Or set up a scheduled run for routine maintenance.
+
+The skill stores its state in your vault at
+`Utility/obsidian-knowledge/`:
+
+- `changelog/` — per-session terse logs (one file per agent session, 1-liners only)
+- `needs-attention.md` — human-resolved worklist
+- `reports/open-questions.md` — regenerated dashboard of `> [!question]` callouts
+
+Historical state was under `.config/obsidian-knowledge/` prior to v1.1.0.
+
+### Vault configuration
+
+For best results, add a `CLAUDE.md` to your vault root with naming
+conventions and instructions to invoke the skill after structural edits.
+
+The vault-organizer respects access zones defined in
+`.claude/vault-zones.yaml`. Create this file to control which folders
+the agent can organize, where indexes are required, and which areas
+are read-only. See the skill's documentation for the expected format.
+
+## License
+
+MIT

obsidian_knowledge-3.19.0/commands/improve-harness.md

@@ -0,0 +1,11 @@
+---
+description: Trigger a meta-improvement side quest to fix harness friction. Provide a free-text description of what's wrong.
+---
+
+# Improve Harness
+
+Trigger the meta-improvement workflow when the harness is causing friction.
+
+Read the skill at `${CLAUDE_PLUGIN_ROOT}/skills/improve-harness/SKILL.md` and execute its workflow with the user's friction description as input.
+
+User-provided friction description: $ARGUMENTS

obsidian_knowledge-3.19.0/commands/scan-secrets.md

@@ -0,0 +1,29 @@
+---
+description: Scan the current vault for leaked secrets on demand. Pass `full` to rebuild the baseline from scratch.
+---
+
+# Scan Vault Secrets
+
+Run the secrets scanner against the vault containing the current working directory. Bypasses the Stop-hook cooldown so it always executes.
+
+The scanner is the same one wired up as a Stop hook (`hooks/scan-vault-secrets.py`); this command runs it in `--manual` mode so findings print to stdout instead of being injected as a Stop block.
+
+## Steps
+
+1. Run the scanner. If `$ARGUMENTS` contains the word `full`, append `--full` to delete the baseline first and force a full rescan; otherwise run an incremental scan.
+
+   ```bash
+   uv run "${CLAUDE_PLUGIN_ROOT}/hooks/scan-vault-secrets.py" --manual
+   ```
+
+   With `full`:
+
+   ```bash
+   uv run "${CLAUDE_PLUGIN_ROOT}/hooks/scan-vault-secrets.py" --manual --full
+   ```
+
+2. Surface the script's stdout verbatim to the user.
+
+3. If findings appeared, briefly summarize what should happen next (audit, redact, or allowlist) using the inline guidance the script already prints. Do not start remediating files automatically — the user decides which findings are real.
+
+User arguments: $ARGUMENTS

obsidian_knowledge-3.19.0/commands/vault-search.md

@@ -0,0 +1,39 @@
+---
+description: Hybrid (BM25 + dense vector) search over the Obsidian vault. Returns top-K paths ranked by relevance. Use this before answering non-trivial questions instead of `rg`.
+---
+
+# Vault Search
+
+Run hybrid retrieval against the vault index. Combines BM25 keyword scoring with dense embedding similarity (Ollama / `bge-m3` by default), fused by memweave. The vector lane gracefully falls back to FTS-only if Ollama is unreachable.
+
+## When to use
+
+- Looking up a topic, person, system, or concept by meaning, not exact phrase.
+- You want freshness + relevance ranking, not a flat grep dump.
+- Paraphrased queries: ask in your own words, the embed lane handles synonyms.
+
+For exact-string lookups (a known function name, a specific token, a literal phrase), `rg` is still faster and exact.
+
+## Steps
+
+1. Run the search. If `$ARGUMENTS` is empty, ask the user what they want to search for and stop.
+
+   ```bash
+   obsidian-knowledge search "$ARGUMENTS"
+   ```
+
+   To include normally-hidden paths (Inbox, Journal, sources), append `--all`:
+
+   ```bash
+   obsidian-knowledge search "$ARGUMENTS" --all
+   ```
+
+   If `obsidian-knowledge` is not found, install it first: `uv tool install obsidian-knowledge`
+
+2. Surface the printed `score  path` lines verbatim.
+
+3. Open the top 1–3 results with `Read` if the user wants the actual content (don't dump everything — paths are cheap, full reads aren't).
+
+4. If the first stderr line says `vector lane off`, mention it once so the user knows results are FTS-only and can fix Ollama if they want semantic search back.
+
+User arguments: $ARGUMENTS

obsidian_knowledge-3.19.0/docs/TODO.md

@@ -0,0 +1,31 @@
+# TODO
+
+Future work for the obsidian-knowledge plugin. Not bugs — design ideas worth tracking until someone picks them up.
+
+## `grade:` YAML frontmatter property
+
+Add a `grade:` field to note frontmatter as a self-rated quality marker (e.g., `grade: A`, `grade: B`, `grade: stub`). Used to:
+
+- Power the `wiki/QUALITY.md` scorecard (currently a stub idea — see vault-organizer SKILL.md history) by aggregating grades per folder
+- Let the SessionStart `doctor.py` digest surface low-graded or ungraded notes alongside convention violations
+- Drive a future `vault-organizer --grade` mode that prompts for grade on any note missing one
+
+**Open questions:** grading scale (letter? 1–5? stub/draft/solid/canonical?); whether to require grades on all wiki notes or only on indexes; whether the grade is human-only or an agent can suggest one based on length, link density, and last-edited date.
+
+## Note-improver agent
+
+A subagent that takes a single wiki note as input and proposes improvements: tighter prose, broken-link triage, missing wikilink suggestions (find related notes that *should* be linked), frontmatter hygiene, grade suggestion (see above). Should be read-only by default, emitting a diff for human review rather than auto-editing.
+
+**Trigger ideas:** invoked manually via `/improve-note <path>`; suggested by `doctor.py` for low-graded notes; chained from `vault-organizer` when it encounters a stub link target that resolves to a real-but-thin note.
+
+**Constraints:** never edits primary file content without confirmation (matches vault-organizer's discipline). Should respect `dg-publish: true` (publish-guard already blocks edits to those).
+
+## Convention-sweep code-block awareness — done
+
+Wikilink-extension check now skips fenced (`` ``` `` / `~~~`) blocks and inline code spans. Logged here only for the next item ↓
+
+## Convention-sweep: skip more false-positive sources
+
+- Skip wikilinks inside HTML comments (`<!-- ... -->`)
+- Skip dated-folder check for files explicitly tagged `type: template` in frontmatter
+- Treat YAML errors in `_drafts/` and similar staging zones as warnings, not violations