woods 2.0.1 → 2.1.0

data/plugin/skills/woods-setup/SKILL.md

@@ -7,6 +7,14 @@ description: Install, upgrade, and first-run-configure the Woods Rails code-inte
 
 Install a structural Index Server first. Embeddings and Console MCP are separate opt-ins.
 
+For builds containing #590 (unreleased after `2.0.0`), managed preflight retains
+intended bundle settings, project receipts omit the unused user config directory,
+and watcher ownership tolerates Git checkout umasks. Check the installed revision
+before relying on this. Keep the supporting executable for update/removal before
+a permanent downgrade; never delete a receipt to bypass a conflict. Use a private
+real directory for plan files when the system temporary path is a symlink. Follow
+the [portability guidance](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md#managed-claude-code-configuration).
+
 ## Managed configuration availability
 
 `woods-agent-config` (#407) is available in Woods `2.0.0.beta3`. First record the
@@ -20,6 +28,13 @@ journals contain private configuration bytes. See the canonical
 for host/Compose preflight, actual Claude file locations, conflict recovery,
 and removal. Preserve manual setup for older installed versions.
 
+For v1-to-v2 upgrades, follow the [migration runbook](https://github.com/lost-in-the/woods/blob/main/docs/UPGRADING_TO_2.md).
+A clean removes snapshot history inside the output directory as well as generated
+index files. Back up consistently and choose whether to retain history before
+cleaning. Remove legacy no-op `log_level` and unsafe-eval settings. Set custom
+Console paths and session-tracer setup in `config/application.rb` before Railtie
+initialization; other Console flags can remain in the normal initializer.
+
 ## Preflight
 
 Read repository instructions and preserve unrelated changes. Record:
@@ -62,6 +77,18 @@ When the preflight records an installed 1.x version, this is an upgrade, not an
 
 Before changing the Gemfile: back up any shared or durable index and agree on a rollback window — never upgrade one in place. After `bundle update woods`, run a full `bin/rails woods:extract` (not incremental; the old index is not a valid baseline across the major), then `woods:validate`. With embeddings configured, re-embed from scratch into a store matching the configured model; expect identifier-level churn in anything that consumed 1.x identifiers (exports, saved queries, downstream tooling). Verify MCP clients against the new surface rather than assuming 1.x tool behavior.
 
+When adopting a reviewed post-2.0 revision containing the unreleased reference
+expansion, establish its [full source-reference baseline](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md#source-reference-baseline-and-upgrades)
+before resuming incremental maintenance. Record the loaded revision; the version
+alone does not identify this planned 2.1 capability.
+
+Supporting unreleased writers also refuse incremental extraction and targeted
+refresh of a flat index with a manifest, or a generation manifest naming a
+writer major version below 2. Run a full `woods:extract` as the upgrade baseline.
+A generation with no writer field can be an early v2 beta; absence alone does
+not identify v1. Read compatibility and a successful validation never replace
+the required full migration.
+
 ## Extract and verify
 
 Structural setup needs no embedding provider:
@@ -74,6 +101,13 @@ bin/rails woods:stats
 
 If extraction fails, reproduce Rails boot and eager loading first. Do not inspect internal payload files when Woods tasks provide the check.
 
+When the installed gem exposes `woods-extract`, use
+`bundle exec woods-extract full` for source capture before Rails boots; follow
+the [source freshness guide](https://github.com/lost-in-the/woods/blob/main/docs/SOURCE_FRESHNESS.md#establish-a-fresh-baseline)
+for custom output paths. In supporting unreleased builds after 2.0.0, this
+launcher prefers the application's executable `bin/rake` and otherwise uses
+`bundle exec rake`. Preserve the application's environment and binstub setup.
+
 Writer-version provenance (#323) is available in Woods `2.0.0.beta3`; check the installed
 gem version's release notes before expecting `woods_status.index.woods_version`. When present,
 it names the last manifest publisher; `server.version` names the MCP reader.
@@ -202,11 +236,19 @@ SessionStart hooks check source content and report missing/failed evidence as
 unknown; silence does not acknowledge queued refresh work. Follow the [hook guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#hooks-for-agent-sessions)
 for transport, retry and custom-root limits.
 
+Supporting unreleased builds after 2.0.0 can publish a usable code index with
+source freshness `unavailable` when evidence exceeds its serialized-size limit.
+Follow `inspect_source_limits` and compare `unavailable.size_bytes` with
+`unavailable.limit_bytes`; an identical full extraction cannot shrink it.
+An oversized launcher handoff still starts a fresh child but cannot establish
+verified preboot capture. Do not label this state current or prescribe repeated
+rebuilds. See the [source evidence limits](https://github.com/lost-in-the/woods/blob/main/docs/SOURCE_FRESHNESS.md).
+
 ## Ask before expanding scope
 
 For pgvector, match the provider output and migration dimensions within 1–2,000. Default `text-embedding-3-large` output (3,072) needs an explicit smaller provider width or another backend; never silently truncate vectors. Early adapter/generator refusal is included in Woods `2.0.0`, so check the installed revision. See the [dimension contract](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#pgvector-postgresql).
 
-Require explicit approval before adding Ollama/OpenAI, pgvector/Qdrant, secrets, Console MCP/live-data access, HTTP transport, or purge overrides. The `:local` preset avoids cloud keys but requires the `sqlite3` gem, an installed/running Ollama service, and a pulled model (`ollama pull nomic-embed-text` by default); `:shared_filesystem` avoids sqlite3 but still uses Ollama. Recommend `gem "tokenizers", "~> 0.5"` for exact counting on dense Ruby source, while stating that it is optional.
+Require explicit approval before adding Ollama/OpenAI, pgvector/Qdrant, secrets, Console MCP/live-data access, HTTP transport, or purge overrides. The `:local` preset avoids cloud keys but requires the `sqlite3` gem, an installed/running Ollama service, and a pulled model (`ollama pull nomic-embed-text` by default); `:shared_filesystem` avoids sqlite3 but still uses Ollama. Do not claim that installing a tokenizer gem establishes exact counts for every model. Supporting builds after 2.0.0 split complete prefixed inputs and request Ollama `truncate: false`; consult the installed embedding guide and its model-specific limits.
 
 ## Handoff
 
@@ -258,8 +300,13 @@ for output/time limits, container root mapping and emitted-hint suppression.
 
 ### Security-patch compatibility preflight
 
-For security-patch candidates after 2.0.0, record the loaded revision and gem
-path as well as the version. Review the [Console compatibility guide](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility)
-and HTTP origin compatibility at that revision before upgrading an authorized
-Console installation. The plugin does not install these fixes or establish that
-a release is published.
+For an authorized Console installation on the 2.0 line, use Woods `2.0.1` or
+later and review the [2.0.1 Console compatibility guide](https://github.com/lost-in-the/woods/blob/v2.0.1/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility)
+before upgrading. Applications remaining on 1.6 should use `1.6.4` and its
+[tagged Console guide](https://github.com/lost-in-the/woods/blob/v1.6.4/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility),
+rather than applying this skill's 2.x setup instructions.
+
+Record the installed version and loaded gem path; also record the locked revision
+for Git-sourced builds. Updating the plugin does not update the gem. The 2.0.1
+maintenance patch does not include the planned 2.1 features marked unreleased
+elsewhere in this skill; continue checking each installed capability.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: woods
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Leah Armstrong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-26 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -215,6 +215,7 @@ files:
 - lib/woods/checks/generation_resolution.rb
 - lib/woods/checks/moved_messages.rb
 - lib/woods/chunking/chunk.rb
+- lib/woods/chunking/contributor_chunks.rb
 - lib/woods/chunking/semantic_chunker.rb
 - lib/woods/console/adapter_family.rb
 - lib/woods/console/audit_logger.rb
@@ -268,10 +269,12 @@ files:
 - lib/woods/embedding/corpus.rb
 - lib/woods/embedding/fake.rb
 - lib/woods/embedding/indexer.rb
+- lib/woods/embedding/input_budget.rb
 - lib/woods/embedding/openai.rb
 - lib/woods/embedding/provider.rb
 - lib/woods/embedding/text_preparer.rb
 - lib/woods/embedding/token_counter.rb
+- lib/woods/embedding/vector_configuration.rb
 - lib/woods/evaluation/ablation_agent_payload.rb
 - lib/woods/evaluation/ablation_executor.rb
 - lib/woods/evaluation/ablation_provenance.rb
@@ -291,17 +294,21 @@ files:
 - lib/woods/export/typed_reader.rb
 - lib/woods/export/unit_facts.rb
 - lib/woods/extracted_unit.rb
+- lib/woods/extraction_identities.rb
 - lib/woods/extractor.rb
 - lib/woods/extractors/action_cable_extractor.rb
+- lib/woods/extractors/assigned_value_discovery.rb
 - lib/woods/extractors/ast_source_extraction.rb
 - lib/woods/extractors/behavioral_profile.rb
 - lib/woods/extractors/caching_extractor.rb
 - lib/woods/extractors/callback_analyzer.rb
+- lib/woods/extractors/class_declarations.rb
 - lib/woods/extractors/component_discovery.rb
 - lib/woods/extractors/concern_extractor.rb
 - lib/woods/extractors/configuration_extractor.rb
 - lib/woods/extractors/controller_extractor.rb
 - lib/woods/extractors/database_view_extractor.rb
+- lib/woods/extractors/declaration_ancestry.rb
 - lib/woods/extractors/declared_parent.rb
 - lib/woods/extractors/decorator_extractor.rb
 - lib/woods/extractors/engine_extractor.rb
@@ -317,6 +324,7 @@ files:
 - lib/woods/extractors/method_parameters.rb
 - lib/woods/extractors/middleware_argument.rb
 - lib/woods/extractors/middleware_extractor.rb
+- lib/woods/extractors/migration_declaration.rb
 - lib/woods/extractors/migration_extractor.rb
 - lib/woods/extractors/model_extractor.rb
 - lib/woods/extractors/package_extractor.rb
@@ -335,6 +343,7 @@ files:
 - lib/woods/extractors/shared_dependency_scanner.rb
 - lib/woods/extractors/shared_utility_methods.rb
 - lib/woods/extractors/source_nesting.rb
+- lib/woods/extractors/standalone_module_discovery.rb
 - lib/woods/extractors/state_machine_extractor.rb
 - lib/woods/extractors/test_mapping_extractor.rb
 - lib/woods/extractors/validator_extractor.rb
@@ -399,6 +408,7 @@ files:
 - lib/woods/mcp/traversal_response.rb
 - lib/woods/mcp/version_aware_tool_dispatch.rb
 - lib/woods/model_name_cache.rb
+- lib/woods/module_reconciliation.rb
 - lib/woods/notion/client.rb
 - lib/woods/notion/exporter.rb
 - lib/woods/notion/mappers/column_mapper.rb
@@ -466,6 +476,8 @@ files:
 - lib/woods/session_tracer/solid_cache_store.rb
 - lib/woods/session_tracer/store.rb
 - lib/woods/session_tracer/unit_resolver.rb
+- lib/woods/source_contributor_validation.rb
+- lib/woods/source_contributors.rb
 - lib/woods/source_inputs/consumer_errors.rb
 - lib/woods/source_inputs/handoff.rb
 - lib/woods/source_inputs/launcher.rb
@@ -474,8 +486,20 @@ files:
 - lib/woods/source_inputs/scanner.rb
 - lib/woods/source_inputs/scopes.rb
 - lib/woods/source_inputs/session.rb
+- lib/woods/source_inputs/stable_reader.rb
 - lib/woods/source_inputs/status.rb
 - lib/woods/source_inputs/verifier.rb
+- lib/woods/source_path_encoding.rb
+- lib/woods/source_references/cache.rb
+- lib/woods/source_references/collector.rb
+- lib/woods/source_references/extraction.rb
+- lib/woods/source_references/inputs.rb
+- lib/woods/source_references/parser_adapter.rb
+- lib/woods/source_references/pass.rb
+- lib/woods/source_references/prism_adapter.rb
+- lib/woods/source_references/registry.rb
+- lib/woods/source_references/runtime_lookup.rb
+- lib/woods/source_references/value_class.rb
 - lib/woods/storage/graph_store.rb
 - lib/woods/storage/inapplicable_backend.rb
 - lib/woods/storage/local_corpus_stats.rb
@@ -496,12 +520,15 @@ files:
 - lib/woods/unblocked/exporter.rb
 - lib/woods/unblocked/rate_limiter.rb
 - lib/woods/unblocked/sync_manifest.rb
+- lib/woods/unblocked/uri_migration.rb
 - lib/woods/update_check.rb
 - lib/woods/util/host_guard.rb
 - lib/woods/util/uuid5.rb
 - lib/woods/version.rb
 - lib/woods/watch/boot_snapshot.rb
+- lib/woods/watch/catch_up.rb
 - lib/woods/watch/child_environment.rb
+- lib/woods/watch/claim_lease.rb
 - lib/woods/watch/cli.rb
 - lib/woods/watch/daemon.rb
 - lib/woods/watch/event_stream.rb
@@ -549,10 +576,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/lost-in-the/woods
-  source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.1
-  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.1/CHANGELOG.md
+  source_code_uri: https://github.com/lost-in-the/woods/tree/v2.1.0
+  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.1.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/lost-in-the/woods/issues
-  documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.1/docs
+  documentation_uri: https://github.com/lost-in-the/woods/tree/v2.1.0/docs
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []