@codewizard-dt/bootstrap 2.19.0 → 2.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -28,7 +28,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
28
28
  | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so the excluded paths are written under a `# bootstrap wiki & agent state (machine-local)` sentinel that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. |
29
29
  | `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical permission deny list (`templates/settings-deny.json` — `Bash(...)` command patterns plus `Edit(...)`/`Read(...)` file-tool patterns) into `~/.claude/settings.json` `permissions.deny`. Entries are opaque strings, so any rule form the permission system accepts merges unchanged. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. A second mode, `--set-key <name> --set-value <json>`, merges a single top-level settings key instead of the deny list (used to register `fileSuggestion`): absent → set; already deep-equal → no-op; present but different → one-line warning and skip, never a clobber. Supplying `--set-key` skips the deny merge entirely; a malformed `--set-value` exits 1, since that is a call-site bug rather than a user's file. |
30
30
  | `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. Always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
31
- | `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list. Five operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`); writes are atomic and reuse the file's existing indentation; and every successful `--set`/`--unset` regenerates the `bootstrap-prefs.README.md` companion beside the values file. See [Preference helper notes](#preference-helper-notes). |
31
+ | `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list. Five operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`), and `--set` also refuses to write into a layer the key's `scope` forbids (`--target` stays exempt); writes are atomic and reuse the file's existing indentation; and every successful `--set`/`--unset` regenerates the `bootstrap-prefs.README.md` companion beside the values file. See [Preference helper notes](#preference-helper-notes). |
32
32
 
33
33
  ## Standalone infra scripts (not wired to the CLI)
34
34
 
@@ -244,16 +244,22 @@ records only whether to install the server. Treat this as a rule when adding a
244
244
  key: if the answer to a question is a credential, the question does not belong in
245
245
  this store.
246
246
 
247
- ### Known gap: `--set` enforces a key's grammar but not its scope
248
-
249
- `--set` validates the *value* against the schema's `values` string, but does not
250
- check that the chosen layer is one the key's `scope` permits. So a `global`-scope
251
- key can be written into a project values file, where `resolve()` will never
252
- consult it — the write succeeds, prints a success line, and has no effect. Filed
253
- as [`BUG-0009`](../../wiki/work/bugs/BUG-0009-set-writes-scope-inert-key-silently.md);
254
- known, not intended. Today the *only* surface that reveals it is the generated
255
- companion's `## Unrecognized keys` section, which lists such a key with
256
- `scope is ... — this layer never consults it, so it has no effect here`.
247
+ ### `--set` enforces a key's grammar AND its scope
248
+
249
+ `--set` validates the *value* against the schema's `values` string, and also
250
+ checks that the chosen layer is one the key's `scope` permits — writing a
251
+ `global`-scope key into a project values file (or vice versa) exits `1` with
252
+ nothing written, naming the actual scope and the layer that would be
253
+ consulted instead. `--target <path>` remains the deliberate, exempt escape
254
+ hatch: it always bypasses the scope check, since it is an explicit
255
+ single-file operation rather than a resolved layer. Fixed as
256
+ [`BUG-0009`](../../wiki/work/bugs/archive/BUG-0009-set-writes-scope-inert-key-silently.md)
257
+ (previously: the write silently succeeded and printed an affirmative line
258
+ while landing in a layer `resolve()` never walks). A scope-inert key can
259
+ still exist — via `--target`, a hand edit, or a values file written by a
260
+ newer bootstrap — and the generated companion's `## Unrecognized keys`
261
+ section still explains it the same way: `scope is ... — this layer never
262
+ consults it, so it has no effect here`.
257
263
 
258
264
  ## Preference-schema notes
259
265
 
@@ -261,7 +267,7 @@ The shape contract for `templates/bootstrap-prefs-schema.json`. JSON cannot carr
261
267
  comments, so the file itself must stay bare — no `$comment` header, no explanatory
262
268
  keys — and everything a reader or a new consumer needs to know about its shape
263
269
  lives here instead. What each individual key *does* is a separate question, and
264
- it is answered by [The key registry — all 19 entries](#the-key-registry--all-19-entries)
270
+ it is answered by [The key registry — all 21 entries](#the-key-registry--all-21-entries)
265
271
  at the end of this section.
266
272
 
267
273
  ### Flat key → entry, and eight fields
@@ -361,7 +367,7 @@ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
361
367
  `"install-global.sh, /git-commit"` fails the suite by construction. Where a
362
368
  run-time prompt exists, it is documented in the key's `detail`.
363
369
 
364
- ### The key registry — all 19 entries
370
+ ### The key registry — all 22 entries
365
371
 
366
372
  Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
367
373
  `installer` first, then `skill` — which is the same grouping and the same order
@@ -370,7 +376,7 @@ schema's `default` field; `unset` in that column means `default: null`, i.e. the
370
376
  key resolves to `unset` until it is answered. This table is transcribed from the
371
377
  JSON; if the two ever disagree, the JSON is right and this table is a bug.
372
378
 
373
- #### `consumer: installer` — 14 entries, read by the setup/update scripts
379
+ #### `consumer: installer` — 16 entries, read by the setup/update scripts
374
380
 
375
381
  | Key | Scope | Consumer | Values | Default | Asked by | What it does |
376
382
  |-----|-------|----------|--------|---------|----------|--------------|
@@ -387,6 +393,8 @@ JSON; if the two ever disagree, the JSON is right and this table is a bug.
387
393
  | `mcp.context7` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Context7 MCP for library documentation lookups |
388
394
  | `mcp.context7Scope` | global | installer | `user \| project` | `unset` | `lib.sh` | Registration scope for the Context7 MCP |
389
395
  | `mcp.playwright` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Playwright MCP for browser automation and UI testing |
396
+ | `obsidian.installApp` | global | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the Obsidian desktop app via the native package manager |
397
+ | `obsidian.plugins` | project | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs) |
390
398
  | `skills.pruneOrphans` | global | installer | `true \| false` | `unset` | `install-global.sh` | Delete stale skill folders in `~/.claude/skills/` left by the wiki rename |
391
399
 
392
400
  The two **(pattern)** rows carry `"dynamic": true` and are key *families*, not
@@ -397,17 +405,18 @@ Unicode-aware slug rule for `gitignore.section.*` are in
397
405
  above; `gitignore.section.*`'s deliberate one-value grammar is in
398
406
  [the section after it](#gitignoresection-has-a-one-value-grammar-on-purpose).
399
407
 
400
- #### `consumer: skill` — 5 entries, read by slash commands at run time
408
+ #### `consumer: skill` — 6 entries, read by slash commands at run time
401
409
 
402
410
  | Key | Scope | Consumer | Values | Default | Asked by | What it does |
403
411
  |-----|-------|----------|--------|---------|----------|--------------|
404
412
  | `gitCommit.versionBump` | either | skill | `auto \| confirm \| never` | `auto` | `install-global.sh` | How `/git-commit` handles the version bump before committing |
405
413
  | `gitCommit.autoPush` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/git-commit` pushes after a successful commit |
406
414
  | `research.persistToRaw` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/research` writes its report and sources to `raw/research/` |
415
+ | `research.autoIngest` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/research` automatically wiki-ingests its saved report |
407
416
  | `uatGenerate.promoteTests` | either | skill | `sibling \| never \| dedicated` | `dedicated` | `install-global.sh` | Where `/uat-generate` writes the unit tests it promotes out of UAT cases |
408
417
  | `gitignore.offerSectionUpdates` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Master gate for the `.gitignore` template section review pass |
409
418
 
410
- These five are the entire `scope: either` population and the entire
419
+ These six are the entire `scope: either` population and the entire
411
420
  `consumer: skill` population — the two sets coincide, because a key that changes
412
421
  what a slash command does is exactly the kind of key a user may want to answer
413
422
  once machine-wide and then override in one checkout.
@@ -693,6 +693,24 @@ if (opts.op === 'set') {
693
693
  );
694
694
  process.exit(1);
695
695
  }
696
+
697
+ // BUG-0009: --set validated the value grammar but never the key's scope,
698
+ // so a global-scope key could be written into a project file (or vice
699
+ // versa) — the write succeeded, printed an affirmative line, and landed
700
+ // in a layer resolve() never walks for that scope, so it silently did
701
+ // nothing. --target is exempt (scopePermitsLayer returns true for it
702
+ // unconditionally); --unset is deliberately left permissive elsewhere,
703
+ // since unsetting an inert key is harmless and is the documented
704
+ // workaround for a key already stuck in the wrong layer.
705
+ if (!scopePermitsLayer(entry, targetLayer)) {
706
+ const correctLayer =
707
+ entry.scope === 'global' ? '--global' : entry.scope === 'project' ? '--project <dir>' : '--global or --project <dir>';
708
+ console.error(
709
+ `Error: "${opts.key}" is scope: ${entry.scope} — the ${targetLayer} layer never reads it, so this write ` +
710
+ `would be inert. Use ${correctLayer} instead, or --target <path> to force a specific file.`
711
+ );
712
+ process.exit(1);
713
+ }
696
714
  }
697
715
 
698
716
  // 'true'/'false' become JSON booleans; everything else is a JSON string.
@@ -197,7 +197,7 @@ settle_skill_pref() {
197
197
  case "$answer" in
198
198
  yes) prefs_set "$key" --global true ; echo " $key = true" ;;
199
199
  no) prefs_set "$key" --global false ; echo " $key = false" ;;
200
- ask) prefs_set "$key" --global ask ; echo " $key = ask (you will be prompted every run; the answer is never stored)" ;;
200
+ ask) prefs_set "$key" --global ask ; echo " $key = ask (the skill will prompt you each time it runs; that per-run answer is never stored)" ;;
201
201
  *) echo " $key left unanswered — today's behavior is unchanged, and you will be asked again next sync." ;;
202
202
  esac
203
203
  PREFS_ASKED=$(( PREFS_ASKED + 1 ))
@@ -232,6 +232,8 @@ else
232
232
  "Should /git-commit push the current branch after committing? (Default no — this turns a local action into a published one. It never creates a branch either way.)"
233
233
  settle_skill_pref research.persistToRaw \
234
234
  "Should /research save its report and sources to raw/research/ by default? (Findings always appear in the reply; this governs the file write only, and you can still decline any single report.)"
235
+ settle_skill_pref research.autoIngest \
236
+ "Should /research automatically fold a saved report into wiki/ (/wiki-ingest) instead of just suggesting the command? (Only runs when a report was actually saved.)"
235
237
  # uatGenerate.promoteTests is the second key that cannot go through
236
238
  # settle_skill_pref: its grammar is sibling|never|dedicated (plus the
237
239
  # parameterized dedicated:<path>), not true|false|ask.
@@ -302,4 +304,15 @@ if [ "$SKIP_MCPS" = false ]; then
302
304
  echo ""
303
305
  fi
304
306
 
305
- echo "Global setup complete (hooks + skills + deny list + hooks wiring + file suggestion + preferences + MCPs)."
307
+ # "preferences" stays unconditional regardless of SKIP_MCPS: step 6 always
308
+ # installs the helper on every pass, whether or not anything was actually
309
+ # asked (a non-tty run still installs it, it just settles no answers) — see
310
+ # BUG-0010. "MCPs" is the one token gated on what actually ran, since step 8
311
+ # is skipped entirely under --skip-mcps and claiming it otherwise overstates
312
+ # the summary's own job (evidence of what ran) on the most common invocation
313
+ # path — both setup-project.sh and update-project.sh call this with --skip-mcps.
314
+ if [ "$SKIP_MCPS" = false ]; then
315
+ echo "Global setup complete (hooks + skills + deny list + hooks wiring + file suggestion + preferences + MCPs)."
316
+ else
317
+ echo "Global setup complete (hooks + skills + deny list + hooks wiring + file suggestion + preferences)."
318
+ fi
@@ -0,0 +1,294 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ # install-obsidian.sh [--interactive] [--project-dir <dir>]
5
+
6
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
7
+ . "$SCRIPT_DIR/lib.sh"
8
+
9
+ INTERACTIVE=false
10
+ PROJECT_DIR=""
11
+
12
+ while [[ $# -gt 0 ]]; do
13
+ case "$1" in
14
+ --interactive) INTERACTIVE=true; shift ;;
15
+ --project-dir) PROJECT_DIR="$2"; shift 2 ;;
16
+ *) shift ;;
17
+ esac
18
+ done
19
+
20
+ # Plugin repo slugs, pinned as named constants (never fetched or derived at
21
+ # runtime) so every releases/latest lookup below is driven by one audited
22
+ # value per plugin.
23
+ PLUGIN_DATAVIEW="blacksmithgu/obsidian-dataview"
24
+ PLUGIN_GRAPH_LINK_TYPES="natefrisch01/Graph-Link-Types"
25
+ # NOTE: prior research flagged an in-progress maintainer transition for
26
+ # Breadcrumbs — verify SkepticMystic/breadcrumbs is still the maintained fork
27
+ # at install time (vs. a community fork) before relying on this constant.
28
+ PLUGIN_BREADCRUMBS="SkepticMystic/breadcrumbs"
29
+
30
+ _install_obsidian_app() {
31
+ local os
32
+ os="$(uname -s)"
33
+
34
+ case "$os" in
35
+ Darwin)
36
+ if [ -d /Applications/Obsidian.app ]; then
37
+ echo " Obsidian.app already installed — skipping."
38
+ return 0
39
+ fi
40
+ brew install --cask obsidian \
41
+ || echo " WARNING: 'brew install --cask obsidian' failed — install Obsidian manually from https://obsidian.md/download"
42
+ ;;
43
+ Linux)
44
+ if flatpak list 2>/dev/null | grep -q md.obsidian.Obsidian; then
45
+ echo " Obsidian (flatpak) already installed — skipping."
46
+ return 0
47
+ fi
48
+ if ! command -v flatpak >/dev/null 2>&1; then
49
+ echo " WARNING: flatpak not found — install Obsidian manually from https://obsidian.md/download"
50
+ return 0
51
+ fi
52
+ flatpak install -y flathub md.obsidian.Obsidian \
53
+ || echo " WARNING: 'flatpak install -y flathub md.obsidian.Obsidian' failed — install Obsidian manually from https://obsidian.md/download"
54
+ ;;
55
+ *)
56
+ echo " Obsidian: no automated installer for '$os' — install manually from https://obsidian.md/download"
57
+ ;;
58
+ esac
59
+ }
60
+
61
+ # _gh_release_asset_url <release_json_file> <asset_name>
62
+ # Prints the browser_download_url of a named asset from a GitHub
63
+ # releases/latest JSON payload already saved to disk; prints nothing if the
64
+ # asset is absent OR the file isn't parseable JSON in the expected shape —
65
+ # callers treat "empty" as the single signal to warn and skip, so a bare
66
+ # `node -e` failure can never trip `set -e` here. Mirrors the
67
+ # JSON.parse + readFileSync + try/catch style used by install-mcps.sh's
68
+ # _disable_project_playwright_locally.
69
+ _gh_release_asset_url() {
70
+ node -e '
71
+ const fs = require("fs");
72
+ try {
73
+ const data = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
74
+ const asset = (data.assets || []).find((a) => a.name === process.argv[2]);
75
+ if (asset && asset.browser_download_url) console.log(asset.browser_download_url);
76
+ } catch (e) {
77
+ // Malformed JSON or unexpected shape — print nothing; the caller warns
78
+ // on the resulting empty string rather than on a node exit code.
79
+ }
80
+ ' "$1" "$2"
81
+ }
82
+
83
+ # _install_obsidian_plugin <vault_dir> <owner_repo>
84
+ # Installs one community plugin from its GitHub releases/latest into
85
+ # <vault_dir>/.obsidian/plugins/<id>/, where <id> comes from the release's
86
+ # manifest.json — the authoritative plugin directory name, NOT the GitHub
87
+ # repo name. manifest.json is downloaded and parsed FIRST, before anything
88
+ # else. Every risky step (curl, JSON parsing, mkdir) warns to stderr and
89
+ # returns rather than aborting the script, so one bad/renamed plugin repo
90
+ # never blocks the other two or the rest of the install.
91
+ #
92
+ # Prints the resolved plugin id to stdout as its ONLY stdout output — bash
93
+ # functions can't return strings, so the caller captures it via:
94
+ # plugin_id="$(_install_obsidian_plugin "$vault_dir" "$owner_repo")"
95
+ # All diagnostics go to stderr (`>&2`) specifically so they never end up
96
+ # inside that captured value.
97
+ _install_obsidian_plugin() {
98
+ local vault_dir="$1" owner_repo="$2"
99
+ local release_tmp manifest_tmp manifest_url main_js_url styles_css_url
100
+ local plugin_id plugin_dir
101
+
102
+ release_tmp="$(mktemp)"
103
+ if ! curl -fsSL "https://api.github.com/repos/${owner_repo}/releases/latest" -o "$release_tmp"; then
104
+ echo " WARNING: ${owner_repo}: failed to fetch latest release — skipping plugin." >&2
105
+ rm -f "$release_tmp"
106
+ return
107
+ fi
108
+ if [ ! -s "$release_tmp" ]; then
109
+ echo " WARNING: ${owner_repo}: empty release response — skipping plugin." >&2
110
+ rm -f "$release_tmp"
111
+ return
112
+ fi
113
+
114
+ manifest_url="$(_gh_release_asset_url "$release_tmp" manifest.json)"
115
+ if [ -z "$manifest_url" ]; then
116
+ echo " WARNING: ${owner_repo}: latest release has no manifest.json asset (or the release JSON was malformed) — skipping plugin." >&2
117
+ rm -f "$release_tmp"
118
+ return
119
+ fi
120
+
121
+ manifest_tmp="$(mktemp)"
122
+ if ! curl -fsSL "$manifest_url" -o "$manifest_tmp"; then
123
+ echo " WARNING: ${owner_repo}: failed to download manifest.json — skipping plugin." >&2
124
+ rm -f "$release_tmp" "$manifest_tmp"
125
+ return
126
+ fi
127
+
128
+ plugin_id="$(node -e '
129
+ const fs = require("fs");
130
+ try {
131
+ const data = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
132
+ if (data && typeof data.id === "string" && data.id) console.log(data.id);
133
+ } catch (e) {
134
+ // Malformed manifest.json — print nothing; caller warns on the empty
135
+ // result below.
136
+ }
137
+ ' "$manifest_tmp")"
138
+ if [ -z "$plugin_id" ]; then
139
+ echo " WARNING: ${owner_repo}: manifest.json is missing/malformed its 'id' field — skipping plugin." >&2
140
+ rm -f "$release_tmp" "$manifest_tmp"
141
+ return
142
+ fi
143
+
144
+ plugin_dir="$vault_dir/.obsidian/plugins/$plugin_id"
145
+ if ! mkdir -p "$plugin_dir"; then
146
+ echo " WARNING: ${owner_repo}: failed to create $plugin_dir — skipping plugin." >&2
147
+ rm -f "$release_tmp" "$manifest_tmp"
148
+ return
149
+ fi
150
+
151
+ # Obsidian requires manifest.json inside the plugin's own directory to
152
+ # recognize and load it — copy the file we already fetched (and already
153
+ # parsed plugin_id from) rather than re-downloading it. See BUG-0011: an
154
+ # earlier version parsed plugin_id from manifest_tmp and then discarded it
155
+ # without ever writing it into plugin_dir, so every plugin ended up enabled
156
+ # in community-plugins.json but missing the manifest Obsidian needs to load it.
157
+ if ! cp "$manifest_tmp" "$plugin_dir/manifest.json"; then
158
+ echo " WARNING: ${owner_repo}: failed to write manifest.json into $plugin_dir — skipping plugin." >&2
159
+ rm -f "$release_tmp" "$manifest_tmp"
160
+ return
161
+ fi
162
+
163
+ main_js_url="$(_gh_release_asset_url "$release_tmp" main.js)"
164
+ if [ -z "$main_js_url" ]; then
165
+ echo " WARNING: ${owner_repo}: latest release has no main.js asset — skipping plugin." >&2
166
+ rm -f "$release_tmp" "$manifest_tmp"
167
+ return
168
+ fi
169
+ if ! curl -fsSL "$main_js_url" -o "$plugin_dir/main.js"; then
170
+ echo " WARNING: ${owner_repo}: failed to download main.js — skipping plugin." >&2
171
+ rm -f "$release_tmp" "$manifest_tmp"
172
+ return
173
+ fi
174
+
175
+ # styles.css is optional — silently skip when the release doesn't ship one.
176
+ styles_css_url="$(_gh_release_asset_url "$release_tmp" styles.css)"
177
+ if [ -n "$styles_css_url" ]; then
178
+ curl -fsSL "$styles_css_url" -o "$plugin_dir/styles.css" \
179
+ || echo " WARNING: ${owner_repo}: failed to download styles.css — continuing without it." >&2
180
+ fi
181
+
182
+ rm -f "$release_tmp" "$manifest_tmp"
183
+ echo "$plugin_id"
184
+ }
185
+
186
+ # _enable_obsidian_plugin <vault_dir> <id>
187
+ # Idempotently adds <id> to <vault_dir>/.obsidian/community-plugins.json —
188
+ # creates the file as ["<id>"] if absent (mkdir -p'ing .obsidian first), else
189
+ # appends <id> only if not already present. Mirrors install-mcps.sh's
190
+ # _disable_project_playwright_locally: warns and skips (never crashes or
191
+ # overwrites) on unparseable JSON or an unexpected (non-array) shape, and
192
+ # never aborts the calling script on any failure.
193
+ _enable_obsidian_plugin() {
194
+ local vault_dir="$1" id="$2"
195
+ node -e '
196
+ const fs = require("fs"), path = require("path");
197
+ const vaultDir = process.argv[1], id = process.argv[2];
198
+ const dir = path.join(vaultDir, ".obsidian");
199
+ const file = path.join(dir, "community-plugins.json");
200
+ let list;
201
+ if (fs.existsSync(file)) {
202
+ let raw;
203
+ try {
204
+ raw = JSON.parse(fs.readFileSync(file, "utf8"));
205
+ } catch (e) {
206
+ console.error(" WARNING: could not parse " + file + " — skipping enable for " + id + ".");
207
+ process.exit(0);
208
+ }
209
+ if (!Array.isArray(raw)) {
210
+ console.error(" WARNING: " + file + " is not a JSON array — skipping enable for " + id + ".");
211
+ process.exit(0);
212
+ }
213
+ list = raw;
214
+ } else {
215
+ list = [];
216
+ }
217
+ if (list.includes(id)) {
218
+ console.log(" " + id + ": already enabled in " + file + ".");
219
+ process.exit(0);
220
+ }
221
+ list.push(id);
222
+ fs.mkdirSync(dir, { recursive: true });
223
+ const tmp = file + ".tmp-" + process.pid;
224
+ fs.writeFileSync(tmp, JSON.stringify(list, null, 2) + "\n");
225
+ fs.renameSync(tmp, file);
226
+ console.log(" " + id + ": enabled in " + file + ".");
227
+ ' "$vault_dir" "$id" || true
228
+ }
229
+
230
+ # ---------------------------------------------------------------------------
231
+ # App install gate
232
+ #
233
+ # Interactive: prompt_yn_sticky handles the ask-once/remember dance itself.
234
+ # Non-interactive: mirror register_optional_mcp's non-interactive branch
235
+ # (install-mcps.sh) exactly — read the stored preference directly via
236
+ # prefs_get, never through a prompt helper (prompt_yn_sticky auto-answers
237
+ # "no" with no tty, which is the wrong default here), and only an explicit
238
+ # stored `false` diverts. `true`, `ask`, and `unset` all proceed with the
239
+ # install, same as register_optional_mcp.
240
+ # ---------------------------------------------------------------------------
241
+ if [ "$INTERACTIVE" = true ]; then
242
+ if prompt_yn_sticky obsidian.installApp --global "Install the Obsidian app (recommended local viewer for wiki/ — https://obsidian.md)? [Y/n]: "; then
243
+ _install_obsidian_app || echo " WARNING: Obsidian app install failed — continuing."
244
+ else
245
+ echo " Skipping Obsidian app install."
246
+ fi
247
+ else
248
+ if [ "$(prefs_get obsidian.installApp --global)" = "false" ]; then
249
+ echo " obsidian.installApp: skipped (remembered decline — change with /bootstrap-config)"
250
+ else
251
+ _install_obsidian_app || echo " WARNING: Obsidian app install failed — continuing."
252
+ fi
253
+ fi
254
+
255
+ # ---------------------------------------------------------------------------
256
+ # Plugin install gate
257
+ #
258
+ # obsidian.plugins is a project-scoped key — the vault root is $PROJECT_DIR,
259
+ # so its prompt_yn_sticky/prefs_get selector is "$PROJECT_DIR" itself (never
260
+ # --global), per the selector-consistency rule documented on prompt_yn_sticky
261
+ # in lib.sh. No $PROJECT_DIR means no vault to install into, so skip outright
262
+ # rather than guessing a location.
263
+ # ---------------------------------------------------------------------------
264
+ if [ -z "$PROJECT_DIR" ]; then
265
+ echo " WARNING: no --project-dir given — skipping Obsidian plugin install."
266
+ else
267
+ install_plugins=false
268
+ if [ "$INTERACTIVE" = true ]; then
269
+ if prompt_yn_sticky obsidian.plugins "$PROJECT_DIR" "Install recommended Obsidian plugins (Dataview, Graph Link Types, Breadcrumbs) into this project's vault config? [Y/n]: "; then
270
+ install_plugins=true
271
+ fi
272
+ else
273
+ # Same non-interactive mirroring as the app-install gate above, applied
274
+ # to the project-scoped key: only a stored `false` skips.
275
+ if [ "$(prefs_get obsidian.plugins "$PROJECT_DIR")" = "false" ]; then
276
+ echo " obsidian.plugins: skipped (remembered decline — change with /bootstrap-config)"
277
+ else
278
+ install_plugins=true
279
+ fi
280
+ fi
281
+
282
+ if [ "$install_plugins" = true ]; then
283
+ for plugin_repo in "$PLUGIN_DATAVIEW" "$PLUGIN_GRAPH_LINK_TYPES" "$PLUGIN_BREADCRUMBS"; do
284
+ plugin_id="$(_install_obsidian_plugin "$PROJECT_DIR" "$plugin_repo")" || plugin_id=""
285
+ if [ -n "$plugin_id" ]; then
286
+ _enable_obsidian_plugin "$PROJECT_DIR" "$plugin_id" || true
287
+ fi
288
+ # Empty $plugin_id means _install_obsidian_plugin already warned
289
+ # internally — just move on to the next plugin.
290
+ done
291
+ else
292
+ echo " Skipping Obsidian plugin install."
293
+ fi
294
+ fi
@@ -167,6 +167,12 @@ run_project_sync() {
167
167
  "$script_dir/merge-gitignore.sh" --interactive "$project_dir"
168
168
  echo ""
169
169
 
170
+ echo "Checking Obsidian setup..."
171
+ if ! "$script_dir/install-obsidian.sh" --interactive --project-dir "$project_dir"; then
172
+ echo "Warning: Obsidian install failed — continuing; re-run update to retry." >&2
173
+ fi
174
+ echo ""
175
+
170
176
  echo "Building MCP tools guide..."
171
177
  installed_mcps="$(detect_installed_mcps "$project_dir")"
172
178
  # Unquoted on purpose: word-split the space-separated names into arguments.
@@ -104,7 +104,7 @@
104
104
  "scope": "global",
105
105
  "consumer": "installer",
106
106
  "summary": "Registration scope for the Context7 MCP",
107
- "detail": "Asked by prompt_scope in lib.sh:387 ('Scope for context7 — [u]ser (default) or [p]roject?'). prompt_scope emits exactly two answers, 'user' and 'project' — it has no local-scope branch, and any reply that does not begin with p or P falls through to user. 'user' registers Context7 once for every project on this machine; 'project' writes the registration into the current project's shareable .mcp.json.",
107
+ "detail": "Asked by prompt_scope in lib.sh:393 ('Scope for context7 — [u]ser (default) or [p]roject?'). prompt_scope emits exactly two answers, 'user' and 'project' — it has no local-scope branch, and any reply that does not begin with p or P falls through to user. 'user' registers Context7 once for every project on this machine; 'project' writes the registration into the current project's shareable .mcp.json.",
108
108
  "values": "user | project",
109
109
  "default": null,
110
110
  "askedBy": "lib.sh"
@@ -118,6 +118,24 @@
118
118
  "default": null,
119
119
  "askedBy": "install-mcps.sh"
120
120
  },
121
+ "obsidian.installApp": {
122
+ "scope": "global",
123
+ "consumer": "installer",
124
+ "summary": "Install the Obsidian desktop app via the native package manager",
125
+ "detail": "Asked by install-obsidian.sh when the Obsidian desktop app is not yet installed on this machine. true installs it via the native package manager — brew on macOS, flatpak on Linux — and, per the standard sticky-prompt semantics, keeps offering it again on every subsequent run until it is actually present. false means the installer stops offering it: the prompt is never shown again on this machine until the key is changed or removed via /bootstrap-config. The app itself is machine-wide, not tied to any one project, which is why this key is global scope, matching mcp.playwright's scope choice.",
126
+ "values": "true | false",
127
+ "default": null,
128
+ "askedBy": "install-obsidian.sh"
129
+ },
130
+ "obsidian.plugins": {
131
+ "scope": "project",
132
+ "consumer": "installer",
133
+ "summary": "Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs)",
134
+ "detail": "Asked by install-obsidian.sh. This is a single bundled prompt covering all three recommended community plugins together — Dataview, Graph Link Types, and Breadcrumbs — rather than one key per plugin, because Dataview is a hard prerequisite for the other two: both Graph Link Types and Breadcrumbs read fields that Dataview indexes, so installing them separately would let a user accept Graph Link Types or Breadcrumbs without Dataview and end up with plugins that silently don't work. true installs and refreshes all three plugin folders into .obsidian/plugins/ and enables them in .obsidian/community-plugins.json on every run. false means the installer stops offering the bundle again until the key is changed or removed via /bootstrap-config. Plugin files live inside this project's own .obsidian/ directory, which is why this key is project scope, matching guides.*'s scope choice.",
135
+ "values": "true | false",
136
+ "default": null,
137
+ "askedBy": "install-obsidian.sh"
138
+ },
121
139
  "skills.pruneOrphans": {
122
140
  "scope": "global",
123
141
  "consumer": "installer",
@@ -154,6 +172,15 @@
154
172
  "default": true,
155
173
  "askedBy": "install-global.sh"
156
174
  },
175
+ "research.autoIngest": {
176
+ "scope": "either",
177
+ "consumer": "skill",
178
+ "summary": "Whether /research automatically wiki-ingests its saved report",
179
+ "detail": "Governs what happens right after Phase 5 writes raw/research/<slug>/index.md — it never runs when that write was suppressed (research.persistToRaw=false, a per-run --no-save, or a declined ask), because there is then no raw/ file to ingest. true immediately follows the full lib/skills/wiki-ingest/SKILL.md procedure against the file just written, non-interactively — Step 2's user checkpoint is skipped because the report was just delivered in this same reply, and the skill proceeds straight through the summary page, entity/concept pages, and the index + log entries. false leaves the wiki untouched and keeps suggesting the manual '/wiki-ingest raw/research/<slug>/index.md' command, which is today's behaviour. 'ask' prompts before ingesting this one report and never writes the answer back to the store — a different mechanism from the per-run override on research.persistToRaw, serving the same 'not this one' need at the ingest step instead of the save step.",
180
+ "values": "true | false | ask",
181
+ "default": false,
182
+ "askedBy": "install-global.sh"
183
+ },
157
184
  "uatGenerate.promoteTests": {
158
185
  "scope": "either",
159
186
  "consumer": "skill",
@@ -22,7 +22,7 @@ Bootstrap remembers your answers to installer and skill prompts in two flat JSON
22
22
  `argument-hint: [view | edit | reset] [--global | --project]`
23
23
 
24
24
  - A mode word (`view` / `edit` / `reset`) preselects the mode and skips the Step C question. Steps A and B still run, and the Step B2 summary is still printed first — a mode word skips a question, never the state read.
25
- - `--global` / `--project` preselects the layer for reads and pins the write layer, subject to the per-key `scope` check in Step E. A pinned layer that the chosen key's `scope` forbids is refused, not silently redirected.
25
+ - `--global` / `--project` preselects the layer for reads and pins the write layer. A pinned layer that the chosen key's `scope` forbids is refused by the helper itself (BUG-0009), not silently redirected — Step E offers only permitted layers so the refusal is rarely hit in practice.
26
26
  - No arguments = the full interactive flow.
27
27
 
28
28
  ---
@@ -106,7 +106,7 @@ Skip this question entirely when a mode word was supplied as an argument — but
106
106
  5. When the chosen key has `consumer: skill`, print this heavier banner:
107
107
  > This is a **skill preference**. Changing it changes what a slash command actually does the next time it runs — not merely whether the installer asks you a question.
108
108
 
109
- Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `research.persistToRaw`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
109
+ Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `research.persistToRaw`, `research.autoIngest`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
110
110
 
111
111
  ## Step E — Choose the value and the layer (edit mode)
112
112
 
@@ -118,7 +118,7 @@ Skip this question entirely when a mode word was supplied as an argument — but
118
118
  - `scope: global` → the global layer only.
119
119
  - `scope: either` → ask which, explaining that **project wins over global, per key**.
120
120
 
121
- Never offer a layer the key's `scope` makes inert. The helper's `--set` does not enforce scope — it will happily write a `global`-scope key into a project file, where nothing ever reads it and the generated companion files it under "Unrecognized keys" with the reason that this layer never consults it. This step is the guard against creating that situation.
121
+ Never offer a layer the key's `scope` makes inert. The helper's `--set` itself now refuses a write into a layer the key's `scope` forbids (exit 1, nothing written — BUG-0009) — attempting to write a `global`-scope key into a project file is rejected rather than silently accepted and later filed under "Unrecognized keys" with a never-consulted reason. This step exists so the user is never offered a choice that would hit that refusal, not because the helper depends on it.
122
122
  3. If `scope` requires the project layer but no project directory was resolved in Step A, abort that edit with an explanation. Do not fall back to the global layer.
123
123
  4. Confirm with one final `AskUserQuestion` (`Yes, apply` / `No, cancel`) showing the exact command about to run:
124
124
  ```
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: research
3
- description: Deep research on a topic using codebase analysis, library docs, and web search — by default also writes the report plus its primary sources to raw/research/<slug>/ (preference-gated by research.persistToRaw; findings are always delivered in the reply)
3
+ description: Deep research on a topic using codebase analysis, library docs, and web search — by default also writes the report plus its primary sources to raw/research/<slug>/ (preference-gated by research.persistToRaw; findings are always delivered in the reply), and can auto-fold a saved report into wiki/ (preference-gated by research.autoIngest)
4
4
  category: researching
5
5
  model: claude-sonnet-5
6
6
  effort: high
@@ -242,18 +242,38 @@ Rules for this phase:
242
242
 
243
243
  ---
244
244
 
245
+ ## Phase 5b: Auto-Ingest Gate (only when Phase 5 actually wrote files)
246
+
247
+ This gate governs whether the report just written under `raw/research/<slug>/` is immediately folded into `wiki/`, instead of leaving `/wiki-ingest raw/research/<slug>/index.md` as a manual follow-up. **Skip this phase entirely when Phase 5 wrote nothing** — a suppressed save (stored `false`, a per-run `--no-save`/`--no-persist`, or a declined `ask`) leaves no `raw/` file to ingest.
248
+
249
+ Read the preference once, after Phase 5 completes:
250
+
251
+ ```bash
252
+ node ~/.claude/bootstrap-prefs.js --get research.autoIngest --project . 2>/dev/null || echo unset
253
+ ```
254
+
255
+ | Value | Behaviour |
256
+ |-------|-----------|
257
+ | `true` | Immediately follow the full procedure in `lib/skills/wiki-ingest/SKILL.md` against the file just written (`raw/research/<slug>/index.md`), non-interactively — skip Step 2's user-checkpoint pause (the report was just delivered in this same reply, so there is nothing new to confirm before proceeding) and go straight through writing/updating the summary page, entity/concept pages, and the `wiki/index.md` + `wiki/log.md` entries. |
258
+ | `false` | Do nothing further. Keep suggesting `/wiki-ingest raw/research/<slug>/index.md` as a manual next step, per Phase 6. |
259
+ | `ask` | Before ingesting, ask the user (AskUserQuestion) whether to fold this report into the wiki now. Honour the answer for **this run only** — never write it back to the store. |
260
+ | `unset` | Do nothing further (today's behaviour — the schema default is `false`), and add one line: "research.autoIngest is unanswered — /research does not auto-ingest by default. Set it with: node ~/.claude/bootstrap-prefs.js --set research.autoIngest --value <true\|false\|ask> --global" |
261
+
262
+ ---
263
+
245
264
  ## Phase 6: Confirm & Suggest Next Steps
246
265
 
247
266
  **If the files were written**, tell the user:
248
267
  - The paths written (`raw/research/<slug>/index.md` and `raw/research/<slug>/sources.md`)
249
268
  - A 2–4 bullet summary of the recommendation
250
- - That the report is now a `raw/` ground-truth source: **"Run `/wiki-ingest raw/research/<slug>/index.md` to synthesize this research into the knowledge base."**
269
+ - **If Phase 5b ingested the report**: say so, and name the wiki pages it created or updated — do not also suggest `/wiki-ingest`, it already ran.
270
+ - **Otherwise**: that the report is now a `raw/` ground-truth source: **"Run `/wiki-ingest raw/research/<slug>/index.md` to synthesize this research into the knowledge base."**
251
271
  - Any follow-on `/task-add` or `/decision-create` suggested by the findings
252
272
 
253
273
  **If nothing was persisted** (stored `false`, a per-run `--no-save`/`--no-persist` override, or a declined `ask`), tell the user:
254
274
  - That no files were written, and which of the three reasons applies
255
275
  - The same 2–4 bullet summary of the recommendation
256
- - Skip the `/wiki-ingest` suggestion entirely — there is no `raw/` file to ingest
276
+ - Skip the `/wiki-ingest` suggestion entirely — there is no `raw/` file to ingest, and Phase 5b never ran either
257
277
  - Any follow-on `/task-add` or `/decision-create` suggested by the findings
258
278
 
259
279
  ---
@@ -279,3 +299,4 @@ Rules for this phase:
279
299
  7) **Never overwrite `raw/` files**: if a target already exists, write `<name>-2.md` / `-3.md` instead, carrying only non-redundant new/changed data with a cross-reference to the prior file
280
300
  8) **No fabricated sources**: every row in `sources.md` is a source you actually consulted; mark unsupported claims as inferences rather than inventing citations
281
301
  9) **`raw/research/` is the only `raw/` path this skill may write to** — never modify or delete anything elsewhere under `raw/`
302
+ 10) **Only run Phase 5b when Phase 5 actually wrote files** — the `research.autoIngest` gate is meaningless (and must not run) against a suppressed save; when it does run with `true`, it hands off to `lib/skills/wiki-ingest/SKILL.md`'s own rules (atomic pages, contradiction callouts, index + log updates), which apply exactly as they do for a manually invoked `/wiki-ingest`
@@ -119,6 +119,8 @@ Populate `depends_on`, `blocks`, and `parallel_safe_with` from Step 5 as lists o
119
119
  # TASK-NNN — Task Title
120
120
 
121
121
  implements::[[DEC-NNNN#DM]] ← only when a decision reference was provided
122
+ depends_on::[[TASK-NNN]] ← one line per dependency from Step 5; omit entirely if none
123
+ blocks::[[TASK-NNN]] ← one line per blocked task from Step 5; omit entirely if none
122
124
 
123
125
  ## Objective
124
126
 
@@ -146,6 +148,8 @@ Agent type annotations: valid types are `general-purpose`, `Explore`, `Plan`.
146
148
 
147
149
  **Decision link** (only when Step 2 found an accepted decision reference): Insert `implements::[[DEC-NNNN#DM]]` as a typed link on the line immediately after the H1, before `## Objective`.
148
150
 
151
+ **Dependency links** (from the Step 5 data, no re-derivation needed): insert one `depends_on::[[TASK-NNN]]` line per dependency and one `blocks::[[TASK-NNN]]` line per blocked task, in the same position — immediately after `implements::` when it's present, or immediately after the H1 when it isn't. *Aside: these typed-link lines are additive to the existing `> **Depends on**:`/`> **Blocks**:` blockquote format, not a replacement, and creating them here does not backfill any pre-existing task file.*
152
+
149
153
  ### Step 9: Update the family index
150
154
 
151
155
  Append to `wiki/work/tasks/index.md`:
@@ -84,6 +84,8 @@ In the same file read, locate the dependency blockquote appearing **immediately
84
84
  - Links follow the pattern `[NNN-slug](NNN-slug.md)` — extract the NNN-slug identifier from each link.
85
85
  - A task with no dependency block at all is treated as having `Depends on: none`, `Blocks: none`, `Parallel-safe with: none`.
86
86
 
87
+ Going forward, task files should also carry one `depends_on::[[TASK-NNN]]` line per dependency and one `blocks::[[TASK-NNN]]` line per blocked task, directly below the blockquote — these are additive typed links for Obsidian/Breadcrumbs graph visualization. `/task-audit`'s own parser continues to read only the blockquote above, unchanged.
88
+
87
89
  ### 2f. Build the Node Record
88
90
 
89
91
  For each task (skipping any moved to completed in 2d), produce a record:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codewizard-dt/bootstrap",
3
- "version": "2.19.0",
3
+ "version": "2.20.0",
4
4
  "description": "Bootstrap Claude Code projects with an LLM Wiki, reusable skills, hooks, and MCP setup",
5
5
  "homepage": "https://github.com/codewizard-dt/bootstrap-wiki#readme",
6
6
  "bugs": {
@@ -0,0 +1,66 @@
1
+ # Dataview Queries for the Wiki
2
+
3
+ > An optional, local-only guide for readers who open this wiki in Obsidian and want live, exploratory views over `wiki/` — on top of, not instead of, the hand/LLM-maintained index files.
4
+
5
+ ---
6
+
7
+ ## 1. What this is (and isn't)
8
+
9
+ [Dataview](https://github.com/blacksmithgu/obsidian-dataview) is a community plugin for Obsidian that lets you write query blocks — `TABLE`, `LIST`, `TASK`, `CALENDAR` — over your vault's markdown files and their frontmatter, and see live, auto-updating results rendered inline in any note.
10
+
11
+ It is **optional**. Nothing in this wiki's schema, tooling, or `/wiki-*` commands depends on Dataview being installed. It is a personal, local convenience for readers who happen to use Obsidian as their markdown viewer — not a wiki dependency, not something CI checks, and not something every contributor needs.
12
+
13
+ **Install it** one of two ways:
14
+
15
+ - Once [`TASK-053`](../../wiki/work/tasks/) lands, run `lib/scripts/install-obsidian.sh` to set up Obsidian with the recommended plugin set (including Dataview) in one step.
16
+ - Or install it manually: open Obsidian → Settings → Community plugins → Browse → search "Dataview" → Install → Enable.
17
+
18
+ Once enabled, paste any of the query blocks below into a scratch note inside your vault (they do not need to live in a committed file) and Dataview will render a live table or list beneath the block, kept in sync as the underlying `wiki/` files change.
19
+
20
+ **Important caveat, repeated at every example below:** these queries are illustrative, exploratory views for your own personal use in Obsidian. They are **not** a replacement for this repo's committed `index.md` files. Per [`wiki/conventions.md`](../../wiki/conventions.md)'s Maps-of-Content convention, those indexes stay flat, hand/LLM-maintained bullet lists — the canonical, git-versioned source of truth that every contributor can read without Obsidian or any plugin installed. Dataview queries are a local lens on top of that canonical data, not a substitute for it.
21
+
22
+ ---
23
+
24
+ ## 2. Example queries
25
+
26
+ ### 2.1 Tasks by status
27
+
28
+ A live table of every task file under `wiki/work/tasks/`, grouped by its `status` frontmatter field — useful for eyeballing what's `todo`, `in-progress`, or `done` without opening `wiki/work/tasks/index.md`.
29
+
30
+ ```dataview
31
+ TABLE status
32
+ FROM "wiki/work/tasks"
33
+ SORT status
34
+ ```
35
+
36
+ *Illustrative only — this is a personal, exploratory view. The committed source of truth for active tasks remains [`wiki/work/tasks/index.md`](../../wiki/work/tasks/index.md), maintained by hand/LLM per the wiki's Maps-of-Content convention.*
37
+
38
+ ### 2.2 Pages with a `contradicts::` link
39
+
40
+ A quick scan for any page that has flagged a contradiction with another page — a useful companion to `/wiki-lint`, which formally audits for these. This matches on the literal `contradicts::` typed-link text appearing anywhere in a page's body (see [`wiki/conventions.md`](../../wiki/conventions.md) for the typed-link convention, `rel::[[target]]`).
41
+
42
+ ```dataview
43
+ LIST
44
+ FROM "wiki"
45
+ WHERE contains(file.text, "contradicts::")
46
+ ```
47
+
48
+ *Illustrative only — a simple text-containment scan, not a substitute for `/wiki-lint`'s structured contradiction audit or the `> **Contradiction:**` callouts it produces. Treat this as a "where should I look" pointer, not a verdict.*
49
+
50
+ ### 2.3 Tools by tag
51
+
52
+ A table of every tool entity page under `wiki/knowledge/entities/tools/`, alongside its `tags` frontmatter field, sorted by filename — handy for spotting which tools share a tag (e.g. "search", "mcp", "deferred") at a glance.
53
+
54
+ ```dataview
55
+ TABLE tags
56
+ FROM "wiki/knowledge/entities/tools"
57
+ SORT file.name
58
+ ```
59
+
60
+ *Illustrative only — a personal cross-cut by tag. The canonical listing of tool entities is whatever links into them from [`wiki/index.md`](../../wiki/index.md) and the concept/source pages that reference them; this query does not replace that link network.*
61
+
62
+ ---
63
+
64
+ ## 3. Why these stay out of the committed wiki
65
+
66
+ Dataview query blocks only render inside Obsidian with the plugin enabled — a plain markdown viewer, GitHub's file preview, or a teammate without the plugin would see the raw ` ```dataview ` fence and nothing else. Committing them into `index.md` files would silently break the wiki for every non-Obsidian reader. Keep queries like these in your own local scratch notes, and let the committed `index.md` files do the job of being readable by everyone, everywhere, with no plugin required.