docbridge 0.10.1 → 0.12.0

package/dist/workers/ruby/lib/docbridge_ruby_scanner/declarations.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "docbridge_ruby_scanner/compat"
+require "docbridge_ruby_scanner/comments"
+
+module DocbridgeRubyScanner
+  # One declaration found in a file, in source order. An unsupported
+  # declaration is recorded only when its comment block carries `@doc`, so it
+  # can be reported; supported declarations are recorded whether or not they
+  # are documented, so audit mode can list them.
+  Declaration = Struct.new(
+    :kind, :symbol_name, :canonical_id, :visibility, :unsupported,
+    :name_start, :name_end, :decl_start, :decl_end, :sig_start, :sig_end, :targets,
+    keyword_init: true,
+  ) do
+    def container?
+      kind == :container
+    end
+  end
+
+  # The lexical state of one class, module, or `class << self` body.
+  Scope = Struct.new(:container, :singleton, :dynamic, :default_visibility, keyword_init: true) do
+    # The canonical ID a method named `name` gets in this scope.
+    def method_id(name, singleton_method)
+      prefix = container ? "#{container}." : ""
+      singleton_method ? "#{prefix}self.#{name}" : "#{prefix}#{name}"
+    end
+
+    def constant_id(name)
+      container ? "#{container}::#{name}" : name.to_s
+    end
+  end
+
+  # Walks the Prism tree and collects declarations from the top level and
+  # class or module bodies; method bodies, blocks, and control flow are never
+  # entered.
+  class DeclarationCollector
+    VISIBILITY_CALLS = { private: "private", protected: "protected", public: "public" }.freeze
+    CLASS_METHOD_CALLS = { private_class_method: "private", public_class_method: "public" }.freeze
+    UNSUPPORTED_CALLS = %i[attr_reader attr_writer attr_accessor alias_method define_method].freeze
+
+    def self.collect(parse_result, converter)
+      collector = new(parse_result, converter)
+      collector.visit_body(parse_result.value.statements, Scope.new(default_visibility: "public"))
+      collector.merge_containers
+    end
+
+    def initialize(parse_result, converter)
+      @comments = CommentIndex.new(parse_result, converter)
+      @declarations = []
+    end
+
+    def visit_body(body, scope)
+      statements = case body
+                   when Prism::StatementsNode then body.body
+                   when Prism::BeginNode then body.statements&.body || []
+                   else []
+                   end
+      statements.each { |node| visit_statement(node, scope) }
+    end
+
+    # Reopenings of one container become one declaration whose annotations
+    # combine, located at the first declaration.
+    def merge_containers
+      first_by_id = {}
+      @declarations.select do |declaration|
+        next true unless declaration.container?
+
+        first = first_by_id[declaration.canonical_id]
+        if first
+          first.targets.concat(declaration.targets)
+          false
+        else
+          first_by_id[declaration.canonical_id] = declaration
+          true
+        end
+      end
+    end
+
+    private
+
+    def visit_statement(node, scope)
+      case node
+      when Prism::ClassNode, Prism::ModuleNode then visit_container(node, scope)
+      when Prism::SingletonClassNode then visit_singleton_class(node, scope)
+      when Prism::DefNode then visit_def(node, scope, nil)
+      when Prism::ConstantWriteNode then visit_constant(node, node.name, node.name_loc, scope)
+      when Prism::ConstantPathWriteNode then visit_constant_path(node, scope)
+      when Prism::CallNode then visit_call(node, scope)
+      when Prism::AliasMethodNode then unsupported_if_annotated(node, node.new_name.location)
+      end
+    end
+
+    def visit_container(node, scope)
+      path = node.constant_path
+      name_loc = path.is_a?(Prism::ConstantPathNode) ? Compat.constant_path_name_loc(path) : path.location
+      id = scope.dynamic || scope.singleton ? nil : qualify(path, scope)
+      return unsupported_if_annotated(node, name_loc) if id.nil?
+
+      add(node, kind: :container, symbol_name: last_segment(id), canonical_id: id, visibility: "public",
+                name_loc: name_loc, sig_end: node.location.end_offset)
+      visit_body(node.body, Scope.new(container: id, default_visibility: "public"))
+    end
+
+    # `class << self` hosts singleton methods; any other receiver is dynamic.
+    def visit_singleton_class(node, scope)
+      unsupported_if_annotated(node, node.class_keyword_loc)
+      dynamic = scope.dynamic || scope.singleton || !node.expression.is_a?(Prism::SelfNode)
+      visit_body(node.body, Scope.new(container: scope.container, singleton: true, dynamic: dynamic,
+                                      default_visibility: "public"))
+    end
+
+    def visit_def(node, scope, explicit_visibility)
+      receiver = node.receiver
+      dynamic = scope.dynamic || (scope.singleton && receiver) || (receiver && !receiver.is_a?(Prism::SelfNode))
+      return unsupported_if_annotated(node, node.name_loc) if dynamic
+
+      singleton = scope.singleton || !receiver.nil?
+      visibility = explicit_visibility || (receiver ? "public" : scope.default_visibility)
+      add(node, kind: :method, symbol_name: node.name.to_s, canonical_id: scope.method_id(node.name, singleton),
+                visibility: visibility, name_loc: node.name_loc, sig_end: signature_end(node))
+    end
+
+    def signature_end(node)
+      return node.rparen_loc.end_offset if node.rparen_loc
+      return node.parameters.location.end_offset if node.parameters
+
+      node.name_loc.end_offset
+    end
+
+    def visit_constant(node, name, name_loc, scope)
+      return unsupported_if_annotated(node, name_loc) if scope.dynamic || scope.singleton
+
+      id = scope.constant_id(name)
+      add(node, kind: :constant, symbol_name: name.to_s, canonical_id: id, visibility: "public",
+                name_loc: name_loc, sig_end: node.location.end_offset)
+    end
+
+    def visit_constant_path(node, scope)
+      name_loc = Compat.constant_path_name_loc(node.target)
+      id = scope.dynamic || scope.singleton ? nil : qualify(node.target, scope)
+      return unsupported_if_annotated(node, name_loc) if id.nil?
+
+      add(node, kind: :constant, symbol_name: last_segment(id), canonical_id: id, visibility: "public",
+                name_loc: name_loc, sig_end: node.location.end_offset)
+    end
+
+    def visit_call(node, scope)
+      return unless node.receiver.nil?
+
+      name = node.name.to_sym
+      if VISIBILITY_CALLS.key?(name)
+        visibility_call(node, scope, VISIBILITY_CALLS[name], scope.singleton)
+      elsif CLASS_METHOD_CALLS.key?(name)
+        visibility_call(node, scope, CLASS_METHOD_CALLS[name], true)
+      elsif UNSUPPORTED_CALLS.include?(name)
+        unsupported_if_annotated(node, node.message_loc || node.location)
+      end
+    end
+
+    # A bare call switches the body's default; arguments name the methods it
+    # applies to, either inline `def`s or already defined methods.
+    def visit_call_arguments(node)
+      node.arguments ? node.arguments.arguments : []
+    end
+
+    def visit_call_target(argument)
+      case argument
+      when Prism::SymbolNode, Prism::StringNode then argument.unescaped
+      end
+    end
+
+    def visibility_call(node, scope, visibility, singleton)
+      arguments = visit_call_arguments(node)
+      if arguments.empty?
+        scope.default_visibility = visibility unless singleton && !scope.singleton
+        return
+      end
+      arguments.each do |argument|
+        if argument.is_a?(Prism::DefNode)
+          visit_def(argument, scope, visibility)
+        elsif (name = visit_call_target(argument))
+          id = scope.method_id(name, singleton)
+          @declarations.each { |d| d.visibility = visibility if d.kind == :method && d.canonical_id == id }
+        end
+      end
+    end
+
+    # Lexical qualification: a leading `::` resets to the top level; a parent
+    # that is not a constant makes the path dynamic (nil).
+    def qualify(path, scope)
+      case path
+      when Prism::ConstantReadNode
+        scope.constant_id(path.name)
+      when Prism::ConstantPathNode
+        name = Compat.constant_path_name(path)
+        return nil if name.nil?
+
+        parent = path.parent
+        return name.to_s if parent.nil?
+
+        prefix = qualify(parent, scope)
+        prefix && "#{prefix}::#{name}"
+      end
+    end
+
+    def last_segment(id)
+      id.split("::").last
+    end
+
+    def unsupported_if_annotated(node, name_loc)
+      block = @comments.block_above(node.location.start_offset)
+      return if block.nil? || block.targets.empty?
+
+      @declarations << Declaration.new(kind: :unsupported, unsupported: true, name_start: name_loc.start_offset,
+                                       name_end: name_loc.end_offset, targets: block.targets)
+    end
+
+    def add(node, kind:, symbol_name:, canonical_id:, visibility:, name_loc:, sig_end:)
+      block = @comments.block_above(node.location.start_offset)
+      decl_start = block ? block.start_offset : node.location.start_offset
+      @declarations << Declaration.new(
+        kind: kind, symbol_name: symbol_name, canonical_id: canonical_id, visibility: visibility,
+        unsupported: false, name_start: name_loc.start_offset, name_end: name_loc.end_offset,
+        decl_start: decl_start, decl_end: node.location.end_offset, sig_start: decl_start, sig_end: sig_end,
+        targets: block ? block.targets : [],
+      )
+    end
+  end
+end

package/dist/workers/ruby/lib/docbridge_ruby_scanner/links.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module DocbridgeRubyScanner
+  # One `@doc` annotation with the byte offsets of its target in the content.
+  DocTarget = Struct.new(:target, :start_offset, :end_offset)
+
+  # `@doc\s+(\S+)` matching and target validation shared with the other
+  # workers.
+  module Links
+    DOC_PATTERN = /@doc[ \t\r\n\f\v]+([^ \t\r\n\f\v]+)/
+
+    module_function
+
+    # Finds every `@doc <target>` in a comment body that starts at
+    # `body_offset` in the content. Offsets are bytes into the content.
+    def doc_targets(body, body_offset)
+      targets = []
+      body.scan(DOC_PATTERN) do
+        match = Regexp.last_match
+        start_offset = body_offset + match.byteoffset(1)[0]
+        target = match[1]
+        targets << DocTarget.new(target, start_offset, start_offset + target.bytesize)
+      end
+      targets
+    end
+
+    # A project-root-relative `file#fragment` that is not the source file.
+    def valid_target?(target, source_file_path)
+      file_path, fragment, *rest = target.split("#", -1)
+      return false unless rest.empty? && fragment && !file_path.empty? && !fragment.empty?
+      return false if file_path.start_with?("/", "./", "../")
+      return false if file_path.include?("\\") || file_path.match?(/[ \t\r\n]/) || fragment.match?(/[ \t\r\n]/)
+      return false if file_path.split("/").include?("..")
+
+      file_path != source_file_path
+    end
+  end
+end

package/dist/workers/ruby/lib/docbridge_ruby_scanner/positions.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DocbridgeRubyScanner
+  # Converts Prism byte offsets into 1-based lines and UTF-16 columns over the
+  # original content. Lines split on "\n" only, so a CRLF file keeps its "\r"
+  # inside the line, and a leading byte order mark counts as one column on
+  # line 1, as the other workers report it.
+  class PositionConverter
+    attr_reader :content
+
+    def initialize(content)
+      @content = content
+      @line_starts = [0]
+      cursor = 0
+      while (newline = content.byteindex("\n", cursor))
+        @line_starts << newline + 1
+        cursor = newline + 1
+      end
+    end
+
+    def position(offset)
+      offset = offset.clamp(0, @content.bytesize)
+      line_index = @line_starts.bsearch_index { |start| start > offset }
+      line_index = line_index.nil? ? @line_starts.size - 1 : line_index - 1
+      line_start = @line_starts[line_index]
+      column = 1
+      @content.byteslice(line_start, offset - line_start).each_codepoint do |codepoint|
+        column += codepoint > 0xFFFF ? 2 : 1
+      end
+      { line: line_index + 1, column: column }
+    end
+
+    def location(file_path, offset)
+      { filePath: file_path }.merge(position(offset))
+    end
+
+    def range(start_offset, end_offset)
+      { start: position(start_offset), end: position(end_offset) }
+    end
+
+    # The content between two byte offsets, clamped to the content.
+    def slice(start_offset, end_offset)
+      start_offset = [start_offset, 0].max
+      end_offset = [end_offset, @content.bytesize].min
+      return "" if start_offset >= end_offset
+
+      @content.byteslice(start_offset, end_offset - start_offset)
+    end
+  end
+end

package/dist/workers/ruby/lib/docbridge_ruby_scanner/probe.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# The `--probe` answer. This file must load on any Ruby that can start the
+# entrypoint, so it requires nothing but the JSON that reports the result and
+# checks the runtime floor before touching Prism.
+module DocbridgeRubyScanner
+  module Probe
+    MINIMUM_VERSION = [3, 3].freeze
+
+    module_function
+
+    def result(ruby_version: RUBY_VERSION, engine: RUBY_ENGINE)
+      return { ok: false, reason: "DocBridge requires CRuby, found #{engine}." } unless engine == "ruby"
+
+      version = ruby_version.split(".").map(&:to_i)
+      if (version <=> MINIMUM_VERSION).negative?
+        return { ok: false, reason: "DocBridge requires CRuby 3.3 or later, found #{ruby_version}." }
+      end
+
+      begin
+        require "prism"
+      rescue LoadError => error
+        return { ok: false, reason: "The bundled Prism gem cannot be loaded: #{error.message}" }
+      end
+      { ok: true, runtime: "cruby", version: ruby_version, prism: Prism::VERSION }
+    end
+  end
+end

package/dist/workers/ruby/lib/docbridge_ruby_scanner/protocol.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "docbridge_ruby_scanner/compat"
+require "docbridge_ruby_scanner/declarations"
+require "docbridge_ruby_scanner/links"
+require "docbridge_ruby_scanner/positions"
+
+module DocbridgeRubyScanner
+  LANGUAGE = "ruby"
+  DEFAULT_VISIBILITY = ["public"].freeze
+
+  # Builds schemaVersion 1 responses. Hash keys are symbols in the order the
+  # other workers emit them; optional fields are omitted, never nil.
+  module Protocol
+    module_function
+
+    def scan_request(request)
+      visibility = request.fetch("options", {})["visibility"]
+      files = request.fetch("files").map do |file|
+        scan_file(file.fetch("filePath"), file.fetch("content"), visibility)
+      end
+      { schemaVersion: 1, requestId: request.fetch("requestId"), language: LANGUAGE, files: files }
+    end
+
+    # A nil visibility means the default, public-only set; an empty list
+    # includes nothing.
+    def scan_file(file_path, content, visibility)
+      content = content.dup.force_encoding(Encoding::UTF_8)
+      converter = PositionConverter.new(content)
+      parse_result = Prism.parse(content, filepath: file_path)
+      return parse_error_response(file_path, parse_result.errors, converter) unless parse_result.errors.empty?
+
+      declarations = DeclarationCollector.collect(parse_result, converter)
+      ResponseBuilder.new(file_path, converter, visibility || DEFAULT_VISIBILITY).build(declarations)
+    end
+
+    def parse_error_response(file_path, errors, converter)
+      first = errors.min_by.with_index { |error, index| [error.location.start_offset, index] }
+      {
+        filePath: file_path, symbols: [], undocumentedSymbols: [], links: [],
+        diagnostics: [{
+          severity: "error", code: "code_parse_error", target: file_path, language: LANGUAGE,
+          message: "Ruby parse error: #{sentence(first.message)}",
+          location: converter.location(file_path, first.location.start_offset),
+        }],
+      }
+    end
+
+    def sentence(message)
+      message.end_with?(".") ? message : "#{message}."
+    end
+  end
+
+  # Turns collected declarations into one file response, applying the
+  # visibility filter and the duplicate rules.
+  class ResponseBuilder
+    def initialize(file_path, converter, visibility)
+      @file_path = file_path
+      @converter = converter
+      @visible = visibility.to_a
+      @response = { filePath: file_path, symbols: [], undocumentedSymbols: [], links: [], diagnostics: [] }
+      @seen_endpoints = {}
+      @duplicate_endpoints = {}
+      @undocumented_endpoints = {}
+    end
+
+    def build(declarations)
+      # An endpoint that any emitted declaration documents is never also
+      # undocumented, whichever comes first in the file.
+      documented = declarations.select { |declaration| emitted?(declaration) && !declaration.targets.empty? }
+      @documented_ids = documented.to_h { |declaration| [declaration.canonical_id, true] }
+      declarations.each { |declaration| add(declaration) }
+      @response
+    end
+
+    private
+
+    def emitted?(declaration)
+      !declaration.unsupported && @visible.include?(declaration.visibility)
+    end
+
+    def add(declaration)
+      unless emitted?(declaration)
+        unsupported(declaration) unless declaration.targets.empty?
+        return
+      end
+
+      symbol = make_symbol(declaration)
+      endpoint = symbol[:endpoint]
+      if declaration.targets.empty?
+        return if @documented_ids[declaration.canonical_id] || @undocumented_endpoints[endpoint]
+
+        @undocumented_endpoints[endpoint] = true
+        @response[:undocumentedSymbols] << symbol
+        return
+      end
+
+      if @seen_endpoints[endpoint]
+        duplicate_symbol(declaration, symbol) unless @duplicate_endpoints[endpoint]
+        @duplicate_endpoints[endpoint] = true
+        return
+      end
+      @seen_endpoints[endpoint] = true
+      @response[:symbols] << symbol
+      add_links(declaration, endpoint)
+    end
+
+    def add_links(declaration, endpoint)
+      seen_targets = {}
+      declaration.targets.each do |target|
+        location = @converter.location(@file_path, target.start_offset)
+        target_range = @converter.range(target.start_offset, target.end_offset)
+        if !Links.valid_target?(target.target, @file_path)
+          @response[:diagnostics] << {
+            severity: "error", code: "invalid_link_target", target: target.target, language: LANGUAGE,
+            source: endpoint,
+            message: "Link target must be a project-root-relative file path and fragment in file#fragment form.",
+            location: location, range: target_range,
+          }
+        elsif seen_targets[target.target]
+          @response[:diagnostics] << {
+            severity: "warning", code: "duplicate_link", target: target.target, language: LANGUAGE,
+            source: endpoint, message: "Duplicate @doc link from #{endpoint} to #{target.target}.",
+            location: location, range: target_range,
+          }
+        else
+          seen_targets[target.target] = true
+          @response[:links] << { source: endpoint, target: target.target, location: location, targetRange: target_range }
+        end
+      end
+    end
+
+    def unsupported(declaration)
+      @response[:diagnostics] << {
+        severity: "warning", code: "unsupported_declaration", target: @file_path, language: LANGUAGE,
+        message: "Ruby declaration annotated with @doc is not supported.",
+        location: @converter.location(@file_path, declaration.name_start),
+        range: @converter.range(declaration.name_start, declaration.name_end),
+      }
+    end
+
+    def duplicate_symbol(declaration, symbol)
+      @response[:diagnostics] << {
+        severity: "error", code: "duplicate_code_symbol", target: symbol[:endpoint], language: LANGUAGE,
+        message: "Duplicate Ruby code symbol endpoint: #{symbol[:endpoint]}",
+        location: @converter.location(@file_path, declaration.name_start), range: symbol[:nameRange],
+      }
+    end
+
+    def make_symbol(declaration)
+      {
+        kind: "code", language: LANGUAGE, filePath: @file_path, symbolName: declaration.symbol_name,
+        canonicalId: declaration.canonical_id, endpoint: "#{@file_path}##{declaration.canonical_id}",
+        location: @converter.location(@file_path, declaration.name_start),
+        nameRange: @converter.range(declaration.name_start, declaration.name_end),
+        declarationRange: @converter.range(declaration.decl_start, declaration.decl_end),
+        signatureRange: @converter.range(declaration.sig_start, declaration.sig_end),
+      }
+    end
+  end
+end

package/dist/workers/ruby/lib/docbridge_ruby_scanner.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# DocBridge Ruby scanner worker: Prism-based `@doc` extraction for
+# schemaVersion 1 of the shared worker protocol. `Protocol` and the
+# declaration collector do the work; `CLI` wraps them for the executable.
+require "docbridge_ruby_scanner/protocol"
+require "docbridge_ruby_scanner/cli"
+
+module DocbridgeRubyScanner
+  module_function
+
+  # Scans one parsed worker request (string keys) and returns the response.
+  def scan_request(request)
+    Protocol.scan_request(request)
+  end
+
+  # Scans one file; a nil visibility means the default `["public"]`.
+  def scan_file(file_path, content, visibility = nil)
+    Protocol.scan_file(file_path, content, visibility)
+  end
+end

package/docs/README.md

@@ -23,6 +23,10 @@ through `docbridge docs show <name>`:
 - [Troubleshooting](user/troubleshooting.md) — recover from configuration,
   scanner, parsing, and link diagnostics
 
+Runnable showcases, one per supported language, live under
+[`examples/`](../examples/). Release history is in the
+[Changelog](../CHANGELOG.md).
+
 ## Automate and integrate
 
 - [Claude Code](integrations/claude-code.md)
@@ -55,13 +59,16 @@ with the specification for the interface whose exact contract you need:
 - [Writing guidelines](contributing/writing.md)
 - [Documentation guidelines](contributing/documentation.md)
 - [Testing](contributing/testing.md)
+- [Adding a language](contributing/adding-a-language.md)
 - [Commit messages](contributing/commits.md)
 - [Pull requests](contributing/pull-requests.md)
 - [Releasing](contributing/releasing.md)
 - [Self-audit baseline](contributing/self-audit.md)
-- [Dogfooding review, September 2026](reports/2026-09-dogfooding-review.md)
+
+## Historical records
 
 Architectural choices are recorded in [Decisions](decisions/README.md).
 Completed delivery records are archived under
-[Completed plans](plans/done/README.md). They are historical context, not
-current user instructions.
+[Completed plans](plans/done/README.md), and dated evidence reports such as the
+[Dogfooding review, September 2026](reports/2026-09-dogfooding-review.md) live
+under `reports/`. They are historical context, not current user instructions.

package/docs/user/automation.md

@@ -45,10 +45,11 @@ Before editing a linked file, read its counterpart:
 docbridge context path/to/file
 ```
 
-After editing, inspect the change set:
+After editing, inspect the change set, including staged and untracked files:
 
 ```sh
-git diff --name-only | docbridge related --stdin --gate
+{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } |
+  docbridge related --stdin --gate
 ```
 
 For every reported counterpart, make one explicit judgment:
@@ -64,10 +65,13 @@ Never remove a valid link just to silence the gate.
 
 Put shared checks in repository hooks rather than one agent's configuration.
 A pre-commit hook can run `docbridge check` as a blocking validity gate and
-then report related files from the staged set:
+then report related files from the staged set. `|| exit $?` stops the hook
+when `check` fails, even without `set -e`. The gate exits `1` on a violation,
+so `|| true` keeps that stage from blocking the commit:
 
 ```sh
-git diff --cached --name-only | docbridge related --stdin --gate
+docbridge check || exit $?
+git diff --cached --name-only | docbridge related --stdin --gate || true
 ```
 
 Add `docbridge context --stdin` when the report should include counterpart

package/docs/user/commands.md

@@ -4,7 +4,9 @@ description: Choose between check, related, context, graph, docs, and upgrade.
 
 # Commands
 
-Use the narrowest command for the question you need to answer.
+Use the narrowest command for the question you need to answer. Every option,
+output shape, and exit status is specified in the
+[CLI specification](https://github.com/salan70/docbridge/blob/main/docs/specs/cli.md).
 
 <!-- @code src/cli/index.ts#run -->
 
@@ -26,10 +28,12 @@ Markdown sections. Add `--json` for machine-readable diagnostics.
 
 ### `related`: find counterpart files
 
-Pass changed paths to learn which linked files may also need attention:
+Pass changed paths to learn which linked files may also need attention. This
+input covers staged, unstaged, and untracked files:
 
 ```sh
-git diff --name-only | docbridge related --stdin
+{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } |
+  docbridge related --stdin
 ```
 
 `--gate` exits `1` when a linked counterpart is absent from the supplied change
@@ -95,6 +99,10 @@ passed, and a non-interactive run without `--yes` fails instead of replacing
 local edits. Configuration, hooks, CI recipes, and your own files are never
 touched.
 
+A copied skill does not update with the package. A skill copied from 0.8.0
+calls guide names that newer versions reject, so refresh it before relying on
+it.
+
 ## Update notification
 
 On an interactive terminal, DocBridge prints one line to stderr when a newer