woods 1.4.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2da9b3b863eb794ca880de7a8b327c7edd22f5ea0b027bd705191af85ea755a
-  data.tar.gz: 31c23f340816f84d3c1acc8e2cf09daa9bb7009179d1bd51cca51f7833c376e5
+  metadata.gz: f001f56232acc78a70a3b8584e1bb7dc7d94d9d0f6fa3d34a749bc963d2a361f
+  data.tar.gz: d9f5e7b0ff143d8d71e4368ce961e946cfc0a5b380793e6f4e190fedae968375
 SHA512:
-  metadata.gz: 69f9bc1e0e83a7894ab0618b1044608f7eb3b869c7a881b04820d033a1a4c66bae7ce56be4c7bd858915679e941354af3f2907c2faa2decac1de8d0a4511913c
-  data.tar.gz: 17360ebaf41923cb074d0b829b8940e24fbd3b7724243a0738fe73ee5a4fbcaf43108194d025a955073088dcf2ea0cd19380304191c41d9b325f02dcee43badd
+  metadata.gz: 5486c78c71a80e6c6445e149ff791dce250cf08503309ac0099e517ea680de3759da359a6e5a819963013f80d4ad3fe83b3f46b43e8d81d560cfaa4034a47552
+  data.tar.gz: 2af74e73f867a605a4ad5ca2770ea148583bd02c1e520ff87fb34bee0ca09be9dad2888875a37c97f3a620e877320dc32ee676e081c911f0c0ad6253bfe8604e

data/CHANGELOG.md

@@ -7,6 +7,214 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-07-16
+
+### Added
+
+- **MCP update awareness.** A new `Woods::UpdateCheck` module performs a best-effort,
+  24h-cached RubyGems lookup for a newer `woods` release (disable with
+  `WOODS_NO_UPDATE_CHECK=1`). The Index Server's `woods_status` tool now reports
+  `server.update` (`current_version` / `latest_version` / `update_available`), and a call to a
+  tool the installed gem doesn't define now returns version-aware guidance ("not available in
+  the installed Woods vX — run `bundle update woods`") instead of a bare "Tool not found". This
+  keeps agents that follow a newer guide skill from silently failing against an older gem.
+- **Claude Code plugin.** The three user-facing guide skills (`woods-setup`,
+  `woods-mcp-config`, `woods-diagnose`) are now packaged as the `woods-plugin`, distributed
+  from the [`lost-in-the/plugins`](https://github.com/lost-in-the/plugins) marketplace suite
+  via a `git-subdir` source (installs fetch only the `plugin/` subtree, not the whole gem).
+  Install with `/plugin marketplace add lost-in-the/plugins` then
+  `/plugin install woods-plugin@lost-in-the-plugins`. Each skill gained a **Version Preflight**
+  step so agents operate only against the installed Woods version (≥ 1.5.0) instead of
+  suggesting tools or tasks an older gem lacks.
+
+### Changed
+
+- The user-facing guide skills moved from `docs/skills/` to `plugin/skills/` to form a valid
+  Claude Code plugin root (`plugin/.claude-plugin/plugin.json`). In-repo dev-workflow skills
+  under `.claude/skills/` are unaffected and remain undistributed.
+
+### Security
+
+- **Console `sample`/`recent` tools now validate `columns` against the model's
+  real columns.** They passed the raw array to ActiveRecord's `.select`, which
+  treats string args as SQL fragments — a crafted column could smuggle a
+  subquery into the SELECT list, bypassing TableGate and column redaction
+  (`pluck` already validated; `sample`/`recent` didn't).
+- **`trace_flow` sanitizes the entry point before building the flow file path.**
+  Only `::`→`__` was applied, so `/` and `..` in a client-supplied entry point
+  could traverse outside the `flows/` directory (a file-read oracle over the
+  HTTP transport). Both path segments now go through the `FilenameUtils`
+  allow-list.
+- **TableGate's SQL table detector no longer misses tables on PostgreSQL.** It
+  hardcoded MySQL literal-stripping, so on PostgreSQL (`standard_conforming_strings`)
+  the MySQL `\'` rule could over-strip and swallow a real `FROM <blocked>`
+  clause. It now strips under both dialects and unions the identifiers.
+- **TableGate no longer misses a table hidden behind a comment marker inside a
+  string literal.** `SqlNoiseStripper` stripped comments *before* literals, so
+  `SELECT '-- ' FROM blocked` had its real `FROM blocked` swallowed as a line
+  comment and slipped past the gate. Comment- and literal-stripping now run in a
+  single combined left-to-right pass (`SqlNoiseStripper.strip_noise`) — a
+  comment marker inside a literal, and a quote inside a comment, are each
+  protected by whichever opens first. `SqlValidator` and the scope-template
+  guard route through the same pass.
+- **`EvalGuard` rejects `%x` shell literals with any delimiter — including
+  whitespace.** The delimiter check excluded `\s`, but a newline is a valid `%x`
+  delimiter (`%x\ncmd\n` compiles and executes), so it slipped through to
+  `instance_eval`. The check now matches any non-word delimiter (`[^\w]`).
+- **`PipelineLock` no longer allows two processes to hold the lock.** Both the
+  stale-lock takeover and the release path had TOCTOU windows: a process that
+  passed the staleness check could rename away — or a plain read-then-unlink
+  release could delete — a competitor's *fresh* lock, so both would "hold" it.
+  Takeover now re-verifies the retired file is still stale (restoring it and
+  backing off if a competitor already took over), and release renames the file
+  aside and re-checks its ownership token before deleting.
+
+### Fixed
+
+- **Incremental extraction no longer corrupts the index.** `rake woods:incremental`
+  overwrote `manifest.json` with zero counts, captured an empty temporal snapshot
+  (making the diff report every unit as deleted), wrote absolute file paths into
+  the index, and re-indexed affected units with a null `estimated_tokens`.
+- **Retrieval ranking signals work on real backends again.** Recency, importance,
+  type-match, and diversity read metadata with symbol keys, but every store
+  returns string keys — so all four scored every unit at their neutral fallback
+  in production. The ranker now reads both key forms.
+- **The embedding cache is now scoped to the provider model.** The cache key was
+  `SHA256(text)` with no model, so a persistent shared backend served the
+  previous model's vector after a model switch. `model_name` is now part of the
+  key — a plain attribute rather than `dimensions`, whose Ollama implementation
+  is a live `embed('test')` probe (keying on it made every cache lookup, hits
+  included, depend on the provider being reachable, and defeated the cache while
+  the backend was down).
+- **`callback_count` reports real counts.** It called the nonexistent
+  `CallbackChain#size`, which raised and left the count silently at 0 for every
+  model; switched to `#count`.
+- **`ResolvedConfig` is now deeply immutable.** Nested strings in
+  `embedding_provider`/`stores` stayed mutable, so the frozen snapshot could be
+  corrupted in place.
+- **Model dependency edges are correct for nested and re-registered units.** The
+  `ModelNameCache` alternation matched a prefixed parent (`Library::Book` for
+  `Library::Book::Chapter`); `DependencyGraph#register` left stale reverse edges
+  on re-registration, inflating incremental blast radius.
+- **Precomputed request flows are no longer empty/stale.** `FlowPrecomputer` ran
+  before unit JSON was written to disk; it now runs after `write_results`.
+- **`trace_flow` resolves precomputed flows again.** The reader allow-listed the
+  entry point but the writer left the action name raw, so a flow for an action
+  outside `[A-Za-z0-9_-]` was written under one filename and looked up under
+  another (silently falling back to live assembly). Both sides now derive the
+  filename from the shared `FilenameUtils.flow_filename`.
+- **Flow annotation no longer resurrects deleted units.** On a full extraction
+  with `precompute_flows`, refreshing a type's `_index.json` rebuilt it from a
+  disk glob of the never-wiped output dir, re-adding unit files for classes
+  deleted from the app since the last run. The index is now rebuilt from the
+  in-memory `@results` (the incremental path, which only holds changed units,
+  still rebuilds from disk).
+- **`FlowAssembler` no longer reports DAG diamonds as cycles**, and
+  `IndexArtifact#promote` no longer accepts sibling directories that merely
+  share a name prefix with `dumps/`.
+- **`implicit_belongs_to` metadata is accurate.** It was flagged on every
+  ActiveRecord presence validator; it now keys on `belongs_to` reflections.
+- **Dependency scanning ignores commented references consistently** across all
+  three passes (a commented `Library::Book` still produced a ghost edge), while
+  keeping references that follow a `#` *inside a string literal* (`link_to "Tag
+  #ruby", Article.recent`). Comment-stripping is string-literal-aware — a plain
+  `#…` regex ate the rest of such lines and dropped the real edge.
+- **`pipeline_extract(incremental: true)` requires `changed_files`** instead of
+  silently re-extracting nothing while reporting success.
+- **`pipeline_diagnose` classifies by the supplied error class** (it built a bare
+  `StandardError`, so every `Timeout`/`Net::`/`Errno` error came back
+  `:unknown`).
+- **`notion_sync` honors the `NOTION_API_TOKEN` env var**, matching the gate that
+  registers the tool (ENV-only hosts previously saw the tool but every call
+  failed). A *blank* env var (docker-compose `${NOTION_API_TOKEN}` interpolation
+  of an unset host variable) is now treated as absent rather than masking a
+  configured token or passing through as a blank bearer. All four resolution
+  sites (exporter, `notion_wired?` gate, tool handler, rake task) share
+  `Woods.resolve_notion_token`.
+- **Embedded documents include the `dependencies:` line again** — the indexer
+  leaves dependency hashes string-keyed and the text preparer only read symbol
+  keys.
+- The MCP CLI integration spec no longer fails under a POSIX/C locale (UTF-8
+  subprocess output is normalized before regex matching).
+- **`CircuitBreaker` admits only a single probe in `half_open`.** It let every
+  concurrent call through while half-open (a thundering herd against a
+  recovering service), and a slow probe's success could wipe failures recorded
+  by an overlapping probe. Concurrent probes are now rejected with
+  `CircuitOpenError`, and an optional `success_threshold` requires N consecutive
+  successful probes to close (default 1). Recovery accounting is also keyed to
+  the per-call probe flag, not the shared state: a stale call admitted while the
+  circuit was *closed* that completes after the transition to `half_open` no
+  longer counts as the probe (it could otherwise close the circuit — or clear a
+  concurrent probe's slot — while the service was still down).
+- **`Retry-After` honors the HTTP-date form.** The Notion and Unblocked clients
+  parsed the header with `.to_f`, turning an HTTP-date into `0.0` and retrying
+  immediately against a throttling server. A shared `Woods::RetryAfter` helper
+  now handles both the delta-seconds and HTTP-date forms.
+- **The MCP pipeline lock is no longer racy under the HTTP transport.** The
+  `@pipeline_mutex ||= Mutex.new` lazy init let two concurrent handlers create
+  separate mutexes and run two pipelines of the same kind; the mutex is now
+  eagerly initialized.
+
+### Changed
+
+- Directory globbing and dependency deduplication across the extractor fleet are
+  centralized in `SharedUtilityMethods#find_files_in_directories` and
+  `SharedDependencyScanner#consolidate_dependencies` (behavior-preserving).
+
+### Documentation
+
+- Added an in-container Index Server section to `DOCKER_SETUP.md` (#139),
+  corrected stale tool counts, corrected backend config examples that referenced
+  nonexistent adapters (#83), and listed the previously-undocumented rake tasks.
+
+## [1.5.0] - 2026-06-23
+
+### Added
+
+- **Rails 6.0 support: the `railties` floor is lowered from `>= 6.1` to `>= 6.0`**
+  (#135). Woods runs cleanly on the Rails 6.0 series — extraction and index-MCP
+  serving need no 6.1-only API. The only 6.1-introduced calls touched
+  (`connection_db_config`, `has_many_inversing`) are `respond_to?`-guarded and
+  degrade on 6.0; a regression spec locks that in.
+- **CI now runs a Rails version matrix plus a booted-app extraction test** (#136).
+  `Appraisals` + `gemfiles/rails_*.gemfile` exercise Rails 6.0, 6.1, 7.0, 7.1,
+  7.2, and 8.0; the matrix excludes invalid Ruby×Rails pairs (e.g. Rails 6.0 only
+  on Ruby 3.0) and adds a **Ruby 4.0** lane. A new booted-app test
+  (`spec/integration/booted_extraction_spec.rb`, against the minimal `spec/dummy`
+  app) boots Rails in-process and runs a real end-to-end extraction, asserting a
+  non-zero unit count and the expected models/associations — gating the
+  version-sensitive introspection path the unit suite (which stubs Rails) can't.
+
+### Changed
+
+- **The Index Server now boots in pattern-only mode by default when no embedding
+  index is present** (#138). Since 1.3.0, `woods-mcp` raised `MissingArtifact` at
+  boot unless `woods.json` existed or `WOODS_ALLOW_AUTODETECT=1` was set — which
+  surprised the most common setup: `rake woods:extract` with no embedding
+  provider, where pattern/regex/structural search works perfectly. The server now
+  auto-detects by default: it serves all always-on tools (`lookup`, `search`,
+  `dependencies`, `structure`, `graph_analysis`, `pagerank`, …) with no env var,
+  and `codebase_retrieve` (semantic search) activates automatically once an
+  embedding provider is configured. Set `WOODS_REQUIRE_INDEX=1` to restore
+  fail-closed behavior (raise `MissingArtifact` when `woods.json` is absent).
+  `WOODS_ALLOW_AUTODETECT` is retained as a no-op for backward compatibility.
+
+### Fixed
+
+- **`manifest.json` no longer reports a stale `git_branch`/`git_sha` in a git
+  worktree** (#137). In a linked worktree, `.git` is a file pointing at the real
+  git directory (often an absolute host path). When that directory couldn't be
+  resolved — e.g. inside a container where the host path isn't mounted — git
+  enrichment failed silently and the branch/SHA fell back to a baked
+  `GIT_BRANCH`/`GIT_SHA` build arg, reporting an unrelated branch. A new
+  `Woods::GitProvenance` resolves provenance with worktree-aware plumbing
+  (`git -C <root> rev-parse`), and emits `"unknown"` when a `.git` is present but
+  the ref can't be resolved (the worktree case) rather than a misleading value.
+  The `GIT_BRANCH`/`GIT_SHA` env vars are honored only when there is **no** `.git`
+  at the root at all (a non-repo checkout — e.g. a Docker `COPY` that excludes
+  `.git` — with build args supplying the SHA) or git is unavailable. Temporal
+  snapshots skip an `"unknown"` SHA so it can't key or collide a snapshot.
+
 ## [1.4.1] - 2026-06-10
 
 ### Fixed

data/CONTRIBUTING.md

@@ -28,7 +28,36 @@ Open an issue describing:
 5. Ensure the test suite passes: `bundle exec rake spec`
 6. Ensure code style passes: `bundle exec rubocop`
 7. Update CHANGELOG.md with your changes
-8. Open a pull request
+8. Complete the **Pre-PR requirements** below
+9. Open a pull request
+
+### Pre-PR requirements
+
+These are hard gates — a PR that fails either is incomplete:
+
+1. **Documentation must be current.** Any doc affected by the change — README, `docs/`, the
+   `plugin/skills/` user guides, `CHANGELOG.md` — must be updated in the *same* PR. Don't ship
+   behavior the docs still describe the old way.
+2. **Investigate plugin-functionality impact.** If the change touches anything the distributed
+   user skills rely on — a rake task, MCP tool or its arguments, an executable (`woods-mcp`,
+   `woods-mcp-start`, `woods-console-mcp`, `woods-mcp-http`), a config key, or setup steps —
+   investigate whether `plugin/skills/{woods-setup,woods-mcp-config,woods-diagnose}` need to
+   change.
+
+### Claude Code plugin changes
+
+`plugin/` is distributed as the `woods-plugin` via the
+[`lost-in-the/plugins`](https://github.com/lost-in-the/plugins) marketplace (a `git-subdir`
+reference to this subtree). Installed users may run an **older** gem than `main`, so:
+
+- If a change adds/removes/renames a tool, task, executable, or config key that a skill
+  documents, **update the skill in the same PR**.
+- The skills carry a Version Preflight (operate only against the installed version). **Land the
+  skill change with the release that ships the capability** — never document a feature in a
+  skill before the version that provides it is released. Bump `plugin/.claude-plugin/plugin.json`
+  `version` when the skill content changes.
+- If the change requires a new marketplace entry, `ref` pin, or metadata edit, open a **paired
+  PR against `lost-in-the/plugins`** and link it from this PR.
 
 ## Development Setup
 
@@ -49,6 +78,39 @@ Woods has two test suites:
 
 All new features need tests. Bug fixes should include a regression test.
 
+### Rails version matrix
+
+The gem supports `railties >= 6.0`. Coverage is split across two CI jobs:
+
+- The base unit `test` job runs `rake spec` across **Ruby 3.0–4.0** on the
+  default (newest) Rails. The unit specs stub Rails, so they run once on the base
+  Gemfile rather than per Rails version.
+- The `rails-matrix` job runs the **booted-app extraction test**
+  (`spec/integration/booted_extraction_spec.rb` against `spec/dummy`) under each
+  supported Rails — 6.0, 6.1, 7.0, 7.1, 7.2, 8.0 — using per-version gemfiles
+  under `gemfiles/`. This is the version-sensitive gate: it boots a real Rails
+  app in-process and runs an extraction. (The booted spec is tagged `:booted_app`
+  and excluded from the default `rake spec`; `WOODS_RUN_BOOTED_APP=1` opts it in,
+  and it must run in its own process — it can't share one with the unit suite.)
+
+The Rails pins live in `Appraisals`; the gemfiles are hand-maintained
+(`eval_gemfile`-ing the base `Gemfile` and pinning Rails) because Appraisal can't
+generate from the conditional base Gemfile. To run a single Rails row locally:
+
+```bash
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
+WOODS_RUN_BOOTED_APP=1 BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile \
+  bundle exec rspec spec/integration/booted_extraction_spec.rb
+```
+
+When adding a Rails line: add it to both `Appraisals` and `gemfiles/`, and add a
+valid Ruby×Rails pair to the `rails-matrix` job in `.github/workflows/ci.yml`.
+**For a row below Rails 7.1**, the gemfile must set `ENV['WOODS_SQLITE3_REQ'] =
+'~> 1.4'` *before* `eval_gemfile` (those Rails versions pin `sqlite3 ~> 1.4` in
+their adapter at load time) and pin `concurrent-ruby '< 1.3.5'` (1.3.5 dropped
+the implicit `require "logger"` those releases rely on under Ruby 3.x) — copy an
+existing `gemfiles/rails_6.0.gemfile` as the template.
+
 ## Code Style
 
 - `frozen_string_literal: true` on every file

data/README.md

@@ -249,6 +249,31 @@ Static tools miss `status_active?`, `status_pending?`, `build_line_item`, `creat
 
 ---
 
+## Claude Code plugin
+
+Woods publishes three **user-facing guide skills** as a Claude Code plugin so agents can walk
+you through setup, MCP configuration, and troubleshooting without leaving your editor:
+
+- `woods-setup` — install, configure, extract, verify, connect MCP servers
+- `woods-mcp-config` — generate a correct `.mcp.json` for your environment
+- `woods-diagnose` — systematic troubleshooting for extraction/MCP/embedding/storage
+
+The plugin ships from the [`lost-in-the/plugins`](https://github.com/lost-in-the/plugins)
+marketplace suite, which references this repo's `plugin/` subtree via a `git-subdir` source —
+so installing fetches only the skill files, not the whole gem:
+
+```bash
+# In Claude Code:
+/plugin marketplace add lost-in-the/plugins
+/plugin install woods-plugin@lost-in-the-plugins
+```
+
+The skill files live in this repo under [`plugin/skills/`](plugin/skills/) (the plugin root is
+[`plugin/`](plugin/), with its manifest at `plugin/.claude-plugin/plugin.json`). Each skill
+opens with a Version Preflight so agents operate only against your installed Woods version. To
+test a local checkout: `claude --plugin-dir /path/to/woods/plugin`. Requires **Woods ≥ 1.5.0**.
+The internal dev-workflow skills under `.claude/skills/` are **not** part of this plugin.
+
 ## Connect to Your AI Tool
 
 Woods ships two MCP servers. Most users only need the **Index Server**.
@@ -448,8 +473,14 @@ rake woods:clean               # Remove index output (alias: woods:clear)
 rake woods:embed               # Embed units for semantic search (alias: woods:nest)
 rake woods:embed_incremental   # Embed changed units only (alias: woods:hone)
 rake woods:notion_sync         # Sync models/columns to Notion (alias: woods:send)
+rake woods:obsidian            # Export to an Obsidian vault — graph view + Bases (alias: woods:vault)
 ```
 
+> **Visualize connections in Obsidian.** `woods:obsidian` renders the codebase as a self-contained
+> [Obsidian](https://obsidian.md) vault: one interlinked note per unit (explore the dependency graph
+> in graph view), a filterable [Bases](https://help.obsidian.md/bases) table, and a `_woods/` machine
+> sidecar so agents can load the whole topology in one read. See [Obsidian Integration](docs/OBSIDIAN_INTEGRATION.md).
+
 ---
 
 ## How It Works Under the Hood
@@ -573,8 +604,10 @@ See [Architecture](docs/ARCHITECTURE.md) for the deep dive — extraction phases
 
 ## Requirements
 
-- Ruby >= 3.0
-- Rails >= 6.1
+- Ruby >= 3.0 (through Ruby 4.0)
+- Rails >= 6.0
+
+CI exercises Rails 6.0, 6.1, 7.0, 7.1, 7.2, and 8.0 across Ruby 3.0–4.0 — see the supported-version table in [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md).
 
 Works with MySQL, PostgreSQL, and SQLite. No additional infrastructure required for basic extraction — embedding and vector search are optional add-ons.
 

data/lib/tasks/woods.rake

@@ -534,8 +534,10 @@ namespace :woods do
     require 'woods/notion/exporter'
 
     config = Woods.configuration
-    # Env var takes precedence over configured value
-    config.notion_api_token = ENV.fetch('NOTION_API_TOKEN', nil) || config.notion_api_token
+    # A non-blank env var takes precedence over the configured value; a blank
+    # NOTION_API_TOKEN is treated as absent. Shared resolution keeps the rake
+    # task, the exporter, and the MCP tool consistent.
+    config.notion_api_token = Woods.resolve_notion_token(config)
 
     unless config.notion_api_token
       puts 'ERROR: Notion API token not configured.'
@@ -650,6 +652,54 @@ namespace :woods do
   desc 'Relay findings to Unblocked (alias for unblocked_sync)'
   task relay: :unblocked_sync
 
+  desc 'Export extraction data to a self-contained Obsidian vault'
+  task obsidian: :environment do
+    require 'woods/obsidian/vault_exporter'
+
+    config = Woods.configuration
+    output_dir = ENV.fetch('WOODS_OUTPUT', config.output_dir)
+    vault_path = ENV.fetch('WOODS_OBSIDIAN_VAULT', File.join(output_dir.to_s, 'obsidian_vault'))
+    # Truthy set, so FLAG=false / FLAG=0 disables rather than silently enabling.
+    env_flag = ->(name) { %w[1 true yes].include?(ENV.fetch(name, '').strip.downcase) }
+
+    puts 'Exporting extraction data to an Obsidian vault...'
+    puts "  Output dir: #{output_dir}"
+    puts "  Vault:      #{vault_path}"
+    puts
+
+    begin
+      exporter = Woods::Obsidian::VaultExporter.new(
+        index_dir: output_dir,
+        vault_path: vault_path,
+        include_source: env_flag.call('WOODS_OBSIDIAN_INCLUDE_SOURCE'),
+        include_framework: env_flag.call('WOODS_OBSIDIAN_INCLUDE_FRAMEWORK'),
+        force_purge: env_flag.call('WOODS_OBSIDIAN_FORCE_PURGE')
+      )
+      stats = exporter.export_all
+    rescue Woods::Obsidian::ExportError => e
+      puts "ERROR: #{e.message}"
+      exit 1
+    end
+
+    puts 'Export complete!'
+    puts "  Notes:    #{stats[:exported]}"
+    puts "  Indexes:  #{stats[:indexes]}"
+    puts "  Swept:    #{stats[:swept]}"
+    puts "  Skipped:  #{stats[:skipped]}"
+    puts
+    puts "Open it in Obsidian: 'Open folder as vault' -> #{vault_path}"
+
+    if stats[:errors].any?
+      puts "  Errors:   #{stats[:errors].size}"
+      stats[:errors].first(5).each { |e| puts "    - #{e}" }
+      puts "    ... and #{stats[:errors].size - 5} more" if stats[:errors].size > 5
+      exit 1
+    end
+  end
+
+  desc 'Render the codebase as an Obsidian vault (alias for obsidian)'
+  task vault: :obsidian
+
   desc 'Generate a random bearer token for woods-mcp-http (WOODS_MCP_HTTP_TOKEN)'
   task :generate_token do
     require 'securerandom'

data/lib/woods/atomic_file.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module Woods
+  # Crash-safe file writes via a temp file + atomic rename.
+  #
+  # Extracted from the pattern in {Woods::IndexArtifact} (whose own
+  # +atomic_write+ is private and instance-level) so any component that writes
+  # many files — e.g. the Obsidian exporter writing a vault of notes — can reuse
+  # it. If the process dies mid-write, the destination file is either the old
+  # content or the new content, never a torn partial.
+  #
+  # @example
+  #   Woods::AtomicFile.write("tmp/woods/obsidian_vault/models/User.md", note_body)
+  module AtomicFile
+    module_function
+
+    # Atomically write +content+ to +path+, creating parent directories.
+    #
+    # @param path [String, Pathname] destination path
+    # @param content [String] file content
+    # @return [void]
+    def write(path, content)
+      path = path.to_s
+      FileUtils.mkdir_p(File.dirname(path))
+      tmp = Tempfile.new('.woods-', File.dirname(path))
+      # Binary mode so the content's bytes (e.g. UTF-8) are written verbatim
+      # regardless of the process's default external encoding.
+      tmp.binmode
+      tmp.write(content)
+      tmp.flush
+      tmp.fsync
+      tmp.close
+      File.rename(tmp.path, path)
+    rescue StandardError
+      tmp&.close
+      tmp&.unlink
+      raise
+    end
+  end
+end

data/lib/woods/cache/cache_middleware.rb

@@ -359,10 +359,27 @@ module Woods
 
       # Build a cache key for an embedding text.
       #
+      # The provider's model_name is folded into the key: a cached embedding
+      # is only valid for the exact model that produced it. Without this, a
+      # persistent shared backend (Redis/SolidCache) returns the previous
+      # model's vector after a model switch or upgrade — different dimensions
+      # error mid-batch, same dimensions silently corrupt similarity scores
+      # (which IndexValidator can't detect, since it checks provider-vs-store
+      # dims, not cache contents).
+      #
+      # model_name (a plain attribute) is used rather than dimensions on
+      # purpose: for every supported provider the model uniquely determines
+      # the vector dimensionality, and `Provider#dimensions` can force a live
+      # network probe (Ollama memoizes `embed('test').length`; OpenAI probes
+      # for unknown models). Keying on dimensions made every cache lookup —
+      # including hits — depend on the provider being reachable, defeating the
+      # cache exactly when the backend is down. model_name distinguishes
+      # models without any I/O.
+      #
       # @param text [String]
       # @return [String]
       def embedding_key(text)
-        Cache.cache_key(:embeddings, Digest::SHA256.hexdigest(text))
+        Cache.cache_key(:embeddings, @provider.model_name.to_s, Digest::SHA256.hexdigest(text))
       end
     end
 

data/lib/woods/console/embedded_executor.rb

@@ -458,6 +458,7 @@ module Woods
       end
 
       def handle_sample(params)
+        validate_select_columns!(params)
         model = resolve_model(params['model'])
         limit = [params.fetch('limit', 5).to_i, 25].min
         scope = apply_scope(model, params['scope'], model_name: params['model'])
@@ -563,6 +564,7 @@ module Woods
       end
 
       def handle_recent(params)
+        validate_select_columns!(params)
         model = resolve_model(params['model'])
         order_by = params.fetch('order_by', 'created_at')
         direction = params.fetch('direction', 'desc')
@@ -903,8 +905,10 @@ module Woods
         # instead of a confusing adapter-level syntax failure. It also
         # neutralises `--` line comments and PostgreSQL dollar-quoted
         # strings that could carry forbidden keywords past a naive scan.
-        # `SqlNoiseStripper` is the same module SqlValidator uses.
-        stripped = SqlNoiseStripper.strip_literals(SqlNoiseStripper.strip_comments(template))
+        # `SqlNoiseStripper` is the same module SqlValidator uses. The
+        # combined single-pass strip_noise resolves comments and literals
+        # together so a comment marker inside a literal can't hide a keyword.
+        stripped = SqlNoiseStripper.strip_noise(template)
         if SCOPE_TEMPLATE_FORBIDDEN.match?(stripped)
           raise ValidationError,
                 'scope template contains forbidden SQL keywords ' \
@@ -928,6 +932,20 @@ module Woods
         scope.any? { |k, _| ScopePredicateParser::SUFFIX_PATTERN.match?(k.to_s) }
       end
 
+      # Validate that any requested +columns+ are real model columns before
+      # they reach +apply_columns+. ActiveRecord treats string args to
+      # +.select+ as raw SQL fragments, so an unvalidated column smuggles a
+      # subquery into the SELECT list (the sample/recent tools skip
+      # +check_sql!+, so this is their only gate). Mirrors +handle_pluck+.
+      #
+      # @param params [Hash] Tool params (uses 'model' and 'columns')
+      # @raise [ArgumentError] if any column is not declared on the model
+      def validate_select_columns!(params)
+        return unless params['columns']
+
+        @model_validator.validate_columns!(params['model'], params['columns'])
+      end
+
       # Apply column selection to a relation.
       #
       # @param relation [ActiveRecord::Relation] The relation

data/lib/woods/console/eval_guard.rb

@@ -194,8 +194,14 @@ module Woods
         # `%x{cmd}`) — the AST flavor of these is `:xstr`/`:xstr_heredoc`,
         # which {Woods::Ast::Parser} may normalize differently across
         # Prism/parser-gem backends. A source-level refusal is both cheap
-        # and impossible to evade via AST normalization.
-        if code.include?('`') || code =~ /%x[{<|!@#(\[]/
+        # and impossible to evade via AST normalization. Ruby accepts ANY
+        # non-word character as the %x delimiter — including whitespace:
+        # `%x\ncmd\n` (newline-delimited) is valid and executes. Match
+        # every non-word char (`[^\w]`, which spans newline/space/tab, not
+        # `[^\w\s]` which excluded them and let `%x\n…` slip through). As a
+        # fail-safe, over-refusing odd-but-harmless source beats letting an
+        # unlisted delimiter through.
+        if code.include?('`') || code =~ /%x[^\w]/
           raise ForbiddenExpressionError, 'payload contains a shell-execution literal (backtick or %x)'
         end