textus 0.54.0 → 0.54.2

data/docs/reference/conventions.md

@@ -8,11 +8,11 @@ Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and i
 ## Key naming
 
 - **Segments are lowercase, kebab- or snake-case.** The grammar `^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$` is the hard limit. Prefer `acme-dashboard` over `acmedashboard` when there's a natural word break.
-- **Lead with the zone in the key path.** `working.projects.acme.dashboard`, not `projects.acme.dashboard`. The zone prefix makes it obvious from the key alone whether a write will be accepted.
+- **Lead with the lane in the key path.** `working.projects.acme.dashboard`, not `projects.acme.dashboard`. The lane prefix makes it obvious from the key alone whether a write will be accepted.
 - **Mirror the directory structure.** If `working.projects.acme.dashboard` resolves to `working/projects/acme/dashboard.md`, do not invent shortcuts that diverge.
 - **Don't pluralise the leaf.** `working.network.org.jane`, not `working.network.org.janes`. Pluralise the container, not the entry.
 
-## Zone layout
+## Lane layout
 
 Recommended top-level layout — the spec allows alternatives, but this is what tooling will default to:
 
@@ -20,12 +20,14 @@ Recommended top-level layout — the spec allows alternatives, but this is what
 .textus/
   manifest.yaml
   schemas/        # YAML schema definitions
-  zones/
+  workflows/      # Textus.workflow DSL files for produced entry acquisition
+  templates/      # ERB templates for publish rendering
+  data/
     knowledge/    # authored truth: identity, voice, decisions — author-holders write
     notebook/     # agent's own durable lane (workspace) — keep-holders write
-    feeds/        # automation-fed external inputs (fetch)
     proposals/    # AI proposals awaiting accept (propose)
-    artifacts/    # generated by build automation — never edit by hand
+    artifacts/    # computed outputs produced by drain — never edit by hand
+    raw/          # write-once external source material (ingest)
 ```
 
 Inside `knowledge/`, group by **domain** (identity, people, projects, decisions, runbooks), not by file type or date. `knowledge.identity.*` is the convention for slow-changing identity facts. Inside `artifacts/`, group by **producer** (`artifacts/catalogs/`, `artifacts/indexes/`) so it's clear which build job owns what.
@@ -47,75 +49,57 @@ The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it
 
 Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
 
-## Derived entries
+## Produced entries
 
-A derived entry declares a `source:` block with a `from:` discriminator (ADR 0093/0094). A `source:` acquires **data** — it never renders; rendering is a publish concern (below). Two `from:` values for derived entries:
-
-**`source: { from: project }`** — textus computes the entry's data on `textus drain` from other store entries. Declarative; nothing shells out. Projection fields are flat under `source:`.
+A produced entry declares `source: { from: external, command: "true", sources: [] }` and a matching `Textus.workflow` block in `.textus/workflows/**/*.rb`. The `source:` acquires **data** — it never renders; rendering is a publish concern (below).
 
 ```yaml
-- key: artifacts.derived.people
-  path: artifacts/derived/people.md
-  zone: artifacts
-  schema: null
-  owner: automation:catalog-people
-  source:
-    from: project
-    select: knowledge.network.org   # prefix or list of prefixes
-    pluck:  [name, relationship, org]
-    sort_by: name
-    format: json                    # the stored form is data
+- key: artifacts.feeds.skills
+  lane: artifacts
+  kind: produced
+  format: json
+  source: { from: external, command: "true", sources: [] }
   publish:
-    - { to: docs/people.md, template: people.mustache }   # render the data through a template
-```
-
-**`source: { from: command }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `doctor`'s `generator_drift` check can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `converge` (default: `automation`).
-
-```yaml
-- key: artifacts.derived.skills
-  path: artifacts/derived/skills.md
-  zone: artifacts
-  owner: automation:catalog-skills
-  source:
-    from: command
-    command: "rake catalog:skills"   # informational; the automation invokes it
-    sources: [knowledge.projects, knowledge.network]
+    - { to: docs/reference/skills.md, template: feeds/skills.erb }
 ```
 
-The build automation is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `source.sources` — same list, recorded twice so a diff proves what was consumed.
-
-Full contract for both shapes is in [`../../SPEC.md` §5.2.1 and §5.2.2](../../SPEC.md). Data transforms (`source.transform:`) and publishing (a `publish:` list of `{ to, template? }` / `{ tree }` targets — render or copy the data) are covered in §5.2–§5.3.
+The matching workflow block:
 
-## Intake and freshness
+```ruby
+# .textus/workflows/feeds/agentskills.rb
+Textus.workflow "agentskills" do
+  match "artifacts.feeds.skills"
 
-External inputs land via `:resolve_handler` hooks, not shell commands. Each intake entry declares `source: { from: handler, handler: <name>, ttl: <dur> }`; re-pull is system-pushed via `drain` (scheduled sweep) and `hook run` (event push) — a `get` never refreshes (ADR 0089):
+  step :fetch do |_, _ctx|
+    { "content" => { "skills" => [...], "count" => 1 } }
+  end
 
-```sh
-textus pulse --output=json                             # `stale` lists expired entries; `next_due_at` is the soonest deadline
-textus drain --as=automation                       # re-pulls every intake entry past its source.ttl
+  publish
+end
 ```
 
-The re-pull cadence is the entry's own `source.ttl`. Age-based garbage collection is the orthogonal `retention:` rule slot in the top-level `rules:` block, matched by glob (`{ ttl, action: drop | archive }`); the two compose — re-pull hourly *and* archive at 90 days:
+`drain` discovers workflows, matches entries, runs the steps, and writes the result back to the entry's data path. Publishing then copies or renders each `publish:` target.
 
-```yaml
-- key: artifacts.feeds.notion.events
-  kind: produced                # produce-method (intake) read from source.from: handler
-  zone: artifacts
-  source: { from: handler, handler: notion, config: { ... }, ttl: 6h }
+Age-based GC uses a `retention:` rule in the top-level `rules:` block:
 
+```yaml
 rules:
-  - match: artifacts.feeds.notion.**
+  - match: artifacts.feeds.**
     retention: { ttl: 90d, action: archive }
 ```
 
-A typical scheduled integration runs `drain` on a cron to re-pull every
-expired feed:
+Full contract in [`../../SPEC.md` §5.2](../../SPEC.md).
+
+## Freshness
+
+A `get` is always a pure read (ADR 0089) — it never triggers a re-produce:
 
 ```sh
-textus drain --as=automation   # in cron / CI — re-pulls all stale feeds
+textus pulse --output=json       # `stale` lists entries past their ttl
+textus drain --as=automation     # re-produces stale entries
 ```
 
-See [`./zones.md` §6](zones.md) for the full intake contract and [`../how-to/writing-hooks.md`](../how-to/writing-hooks.md) for writing custom handlers.
+See [`./lanes.md`](lanes.md) for lane semantics and [`../how-to/configuring-lanes.md`](../how-to/configuring-lanes.md) for setting up produced entries and workflows.
 
 ### Read vs. refresh
 
@@ -141,11 +125,11 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 
 The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](../architecture/decisions/0018-manifest-carving.md), [ADR 0017](../architecture/decisions/0017-envelope-io-split.md), [ADR 0022](../architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](../architecture/decisions/0023-uniform-use-case-shape.md).
 
-- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
+- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(lane)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
 - **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
 - **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
 
-The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.
+The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/4`) are unchanged.
 
 ## Pairing with other tools
 

data/lib/textus/action/ingest.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "date"
+require "digest"
 
 module Textus
   module Action
@@ -22,6 +23,8 @@ module Textus
       view { |env| { "key" => env.key, "uid" => env.uid, "etag" => env.etag } }
 
       SOURCE_KINDS = %w[url file asset].freeze
+      CONTENT_HASH_ALGO = "sha256"
+      TOMBSTONE_RETAIN = %w[ingested_at].freeze
 
       def initialize(kind:, slug:, url: nil, path: nil, zone: nil, label: nil)
         super()
@@ -43,7 +46,22 @@ module Textus
           action: :ingest, actor: call.role, key: key,
         )
 
-        write_raw_entry(key, now, container, call)
+        content_hash = compute_content_hash
+        writer = Textus::Envelope::Writer.from(container: container, call: call)
+        mentry = container.manifest.resolver.resolve(key).entry
+        ts = now.iso8601
+        structured = build_structured(ts, container, now, content_hash)
+
+        index = Textus::Ports::RawIndex.new(root: container.root)
+        duplicate_key = find_duplicate(index, content_hash)
+
+        if duplicate_key && duplicate_key != key
+          supersede_entry(duplicate_key, key, structured, container, call, index)
+        else
+          env = write_raw_entry(key, structured, mentry, writer)
+          index.upsert(content_hash: content_hash, url: @url, key: key)
+          env
+        end
       end
 
       private
@@ -70,50 +88,100 @@ module Textus
         "raw.#{date}.#{@kind}-#{@slug}"
       end
 
-      def write_raw_entry(key, now, container, call)
-        ts     = now.iso8601
-        mentry = container.manifest.resolver.resolve(key).entry
-        writer = Textus::Envelope::Writer.from(container: container, call: call)
+      def compute_content_hash
+        digest = Digest::SHA256.new
+        case @kind
+        when "url"
+          digest.update(@url)
+        when "file", "asset"
+          digest.file(@path)
+        end
+        "#{CONTENT_HASH_ALGO}:#{digest.hexdigest}"
+      end
 
+      def build_structured(timestamp, container, now, content_hash)
+        base = { "ingested_at" => timestamp, "content_hash" => content_hash }
         case @kind
         when "url"
-          structured = {
-            "ingested_at" => ts,
-            "source" => { "kind" => "url", "url" => @url, "label" => @label || @url },
-            "body" => nil,
-          }
-          writer.put(key, mentry: mentry,
-                          payload: Textus::Envelope::Writer::Payload.new(
-                            meta: nil, body: nil, content: structured,
-                          ))
+          base.merge("source" => { "kind" => "url", "url" => @url, "label" => @label || @url },
+                     "body" => nil)
         when "file"
           body_content = File.read(@path)
-          structured = {
-            "ingested_at" => ts,
-            "source" => { "kind" => "file", "path" => @path,
-                          "label" => @label || File.basename(@path) },
-            "body" => body_content,
-          }
-          writer.put(key, mentry: mentry,
-                          payload: Textus::Envelope::Writer::Payload.new(
-                            meta: nil, body: nil, content: structured,
-                          ))
+          base.merge("source" => { "kind" => "file", "path" => @path,
+                                   "label" => @label || File.basename(@path) },
+                     "body" => body_content)
         when "asset"
           asset_rel = copy_asset_file(container, now)
-          structured = {
-            "ingested_at" => ts,
-            "source" => { "kind" => "asset",
-                          "label" => @label || File.basename(@path) },
-            "asset" => asset_rel,
-            "body" => nil,
-          }
-          writer.put(key, mentry: mentry,
-                          payload: Textus::Envelope::Writer::Payload.new(
-                            meta: nil, body: nil, content: structured,
-                          ))
+          base.merge("source" => { "kind" => "asset",
+                                   "label" => @label || File.basename(@path) },
+                     "asset" => asset_rel,
+                     "body" => nil)
         end
       end
 
+      def write_raw_entry(key, structured, mentry, writer)
+        writer.put(key, mentry: mentry,
+                        payload: Textus::Envelope::Writer::Payload.new(
+                          meta: nil, body: nil, content: structured,
+                        ))
+      end
+
+      def find_duplicate(index, content_hash)
+        dup = index.find_by_hash(content_hash)
+        return dup if dup
+
+        return unless @kind == "url"
+
+        index.find_by_url(@url)
+      end
+
+      def supersede_entry(old_key, new_key, structured, container, call, index)
+        old_mentry = container.manifest.resolver.resolve(old_key).entry
+        writer = Textus::Envelope::Writer.from(container: container, call: call)
+
+        reader = Textus::Envelope::Reader.from(container: container)
+        old_env = reader.read(old_key)
+        old_content = old_env&.content || {}
+        tombstone = {}
+        TOMBSTONE_RETAIN.each do |k|
+          tombstone[k] = old_content[k] if old_content.key?(k)
+        end
+        source_kind = old_content.dig("source", "kind")
+        tombstone["source"] = { "kind" => source_kind } if source_kind
+        tombstone["superseded_by"] = new_key
+
+        writer.put(old_key, mentry: old_mentry,
+                            payload: Textus::Envelope::Writer::Payload.new(
+                              meta: nil, body: nil, content: tombstone,
+                            ))
+
+        structured["supersedes"] = old_key
+        env = write_raw_entry(new_key, structured, container.manifest.resolver.resolve(new_key).entry, writer)
+
+        move_asset_file(container, old_content["asset"]) if @kind == "asset" && old_content["asset"]
+
+        index.upsert(content_hash: structured["content_hash"], url: @url, key: new_key)
+        env
+      end
+
+      def move_asset_file(container, old_asset_rel)
+        old_path = File.join(container.root, "assets", old_asset_rel)
+        return unless File.exist?(old_path)
+
+        now = Time.now.utc
+        date_path = now.strftime("%Y/%m/%d")
+        filename = File.basename(old_path)
+        new_dir = File.join(container.root, "assets", "raw", date_path, @zone)
+        new_path = File.join(new_dir, filename)
+
+        return if old_path == new_path
+
+        FileUtils.mkdir_p(new_dir)
+        FileUtils.mv(old_path, new_path)
+      rescue Errno::ENOENT, Errno::EACCES => e
+        warn "[textus ingest] could not move asset #{old_asset_rel}: #{e.message}"
+      end
+
       def copy_asset_file(container, now)
         date_path = now.strftime("%Y/%m/%d")
         filename  = File.basename(@path)

data/lib/textus/action/pulse.rb

@@ -46,7 +46,7 @@ module Textus
       end
 
       def index_etag(container)
-        path = container.manifest.resolver.resolve("artifacts.index").path
+        path = container.manifest.resolver.resolve("artifacts.system.index").path
         File.exist?(path) ? container.file_store.etag(path) : nil
       rescue Textus::Error
         nil

data/lib/textus/boot.rb

@@ -158,9 +158,9 @@ module Textus
         "contract_etag" => etag,
         "lanes" => lanes_for(manifest),
         "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
-        "orientation" => read_artifact_content(container, "artifacts.orientation"),
+        "orientation" => read_artifact_content(container, "artifacts.config.orientation"),
         "context" => read_boot_context(container),
-        "index_key" => "artifacts.index",
+        "index_key" => index_key_if_present(container),
         "agent_protocol" => agent_protocol(manifest),
       }.compact
     end
@@ -188,6 +188,13 @@ module Textus
       nil
     end
 
+    def self.index_key_if_present(container)
+      res = container.manifest.resolver.resolve("artifacts.system.index")
+      res.path && File.exist?(res.path) ? "artifacts.system.index" : nil
+    rescue Textus::Error
+      nil
+    end
+
     def self.lanes_for(manifest)
       manifest.data.declared_lane_kinds.keys.map do |name|
         verb = manifest.policy.verb_for_lane(name)

data/lib/textus/container.rb

@@ -1,10 +1,26 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
 module Textus
   # Single capability record handed to every use case. Replaces the
   # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store
   # (see Store#initialize); Store delegates its readers to this record,
-  # so this `Data.define` is the single source of truth for the field set.
-  Container = Data.define(
-    :manifest, :file_store, :schemas, :root,
-    :audit_log, :workflows, :gate
-  )
+  # so this struct is the single source of truth for the field set.
+  class Container < Dry::Struct
+    attribute :manifest,   Types::Any
+    attribute :file_store, Types::Any
+    attribute :schemas,    Types::Any
+    attribute :root,       Types::String
+    attribute :audit_log,  Types::Any
+    attribute :workflows,  Types::Any
+    attribute :gate,       Types::Any
+
+    def with(**attrs) = self.class.new(to_h.merge(attrs))
+
+    def initialize(*)
+      super
+      freeze
+    end
+  end
 end

data/lib/textus/core/freshness/verdict.rb

@@ -9,7 +9,7 @@ module Textus
       # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
       # full field set. It emits the legacy keys ("stale", "stale_reason",
       # "fetching", and "fetch_error" when present) so the CLI JSON wire stays
-      # byte-identical with textus/3. The gem-side fields `checked_at` and
+      # byte-identical with textus/4. The gem-side fields `checked_at` and
       # `ttl_remaining_ms` are NOT emitted on the wire.
       Verdict = Data.define(
         :stale, :fetching, :reason, :fetch_error, :checked_at, :ttl_remaining_ms

data/lib/textus/cursor_store.rb

@@ -1,7 +1,7 @@
 require "fileutils"
 
 module Textus
-  # Per-role cursor cache under <root>/.run/state/cursor.<role>. A convenience so
+  # Per-role cursor cache under <root>/.state/cursors/<role>. A convenience so
   # `textus pulse` (no --since) means "since I last looked". Gitignored;
   # losing it just re-emits recent deltas, never corrupts the store. ADR 0036/0038.
   class CursorStore

data/lib/textus/doctor/check/protocol_version.rb

@@ -13,13 +13,13 @@ module Textus
 
           doc = YAML.safe_load_file(path, aliases: false) || {}
           version = doc["version"]
-          return [] if version == "textus/3"
+          return [] if version == "textus/4"
 
           [{
             "code" => "protocol_mismatch",
             "severity" => "error",
-            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
-            "hint" => "Upgrade the store's manifest version to textus/3 (see CHANGELOG for breaking changes).",
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/4.",
+            "hint" => "Upgrade the store's manifest version to textus/4 (see CHANGELOG for breaking changes).",
           }]
         end
 
@@ -31,14 +31,14 @@ module Textus
 
           doc = YAML.safe_load_file(path, aliases: false) || {}
           version = doc["version"]
-          return [] if version == "textus/3"
+          return [] if version == "textus/4"
 
           [{
             "code" => "protocol_mismatch",
             "level" => "error",
             "subject" => path,
-            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
-            "fix" => "Upgrade the store's manifest version to textus/3 (see CHANGELOG for breaking changes).",
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/4.",
+            "fix" => "Upgrade the store's manifest version to textus/4 (see CHANGELOG for breaking changes).",
           }]
         end
       end

data/lib/textus/doctor/check/stale_reviewed_stamp.rb

@@ -0,0 +1,54 @@
+module Textus
+  module Doctor
+    class Check
+      # Warns when a knowledge-lane doc's `**reviewed** YYYY-MM (vX.Y)` stamp
+      # is more than MINOR_THRESHOLD minor versions behind Textus::VERSION.
+      # The stamp is the human staleness signal declared in docs conventions
+      # (knowledge.docs-index); this check makes it machine-enforced.
+      class StaleReviewedStamp < Check
+        STAMP_RE = /\*\*reviewed\*\*\s+\d{4}-\d{2}\s+\(v(\d+\.\d+(?:\.\d+)?)\)/
+        MINOR_THRESHOLD = 5
+
+        def call
+          current_minor = parse_minor(Textus::VERSION)
+          issues = []
+
+          manifest.resolver.enumerate.each do |row|
+            next unless row[:key].to_s.start_with?("knowledge.")
+            next unless row[:path] && File.file?(row[:path])
+
+            body = File.read(row[:path])
+            m = body.match(STAMP_RE)
+            next unless m
+
+            reviewed_minor = parse_minor(m[1])
+            behind = current_minor - reviewed_minor
+            next unless behind > MINOR_THRESHOLD
+
+            issues << stale_issue(row[:key], m[1], behind)
+          end
+
+          issues
+        end
+
+        private
+
+        def parse_minor(version_str)
+          version_str.sub(/\Av/, "").split(".").map(&:to_i)[1] || 0
+        end
+
+        def stale_issue(key, stamp_version, behind)
+          current_short = Textus::VERSION[/\A\d+\.\d+/]
+          {
+            "code" => "stale_reviewed_stamp",
+            "level" => "warning",
+            "subject" => key.to_s,
+            "message" => "reviewed at v#{stamp_version}; current is v#{Textus::VERSION} " \
+                         "(#{behind} minor versions behind, threshold is #{MINOR_THRESHOLD})",
+            "fix" => "review the doc and update the stamp to: **reviewed** YYYY-MM (v#{current_short})",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -23,6 +23,7 @@ module Textus
       Check::GeneratorDrift,
       Check::RawAssetPaths,
       Check::NotebookSources,
+      Check::StaleReviewedStamp,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze

data/lib/textus/envelope.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
+require "dry-struct"
+
 module Textus
-  Envelope = Data.define(
-    :protocol, :key, :lane, :owner, :path, :format,
-    :uid, :etag, :schema_ref, :meta, :body, :content, :freshness
-  ) do
+  class Envelope < Dry::Struct
+    attribute :protocol,   Types::String
+    attribute :key,        Types::String
+    attribute :lane,       Types::String
+    attribute :owner,      Types::String.optional
+    attribute :path,       Types::String
+    attribute :format,     Types::FormatName
+    attribute :etag,       Types::String
+    attribute :uid,        Types::String.optional
+    attribute :schema_ref, Types::String.optional
+    attribute :meta,       Types::Hash.default({}.freeze)
+    attribute :body,       Types::String.optional
+    attribute :content,    Types::Any.optional
+    attribute :freshness,  Types::Any.optional
+
     # rubocop:disable Metrics/ParameterLists
     def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
       # rubocop:enable Metrics/ParameterLists
@@ -30,6 +43,8 @@ module Textus
       v.is_a?(String) ? v : nil
     end
 
+    def with(**attrs) = self.class.new(to_h.merge(attrs))
+
     def to_h_for_wire
       h = {
         "protocol" => protocol,
@@ -49,8 +64,6 @@ module Textus
       h
     end
 
-    alias_method :zone, :lane
-
     def stale?
       return false if freshness.nil?
 

data/lib/textus/errors.rb

@@ -217,7 +217,7 @@ module Textus
     def initialize(old_flag, new_flag)
       super(
         "flag_renamed",
-        "#{old_flag} was renamed in textus/3 — use #{new_flag}",
+        "#{old_flag} was renamed in textus/4 — use #{new_flag}",
         details: { "old" => old_flag, "new" => new_flag },
         hint: "Use #{new_flag} instead.",
         exit_code: 2,

data/lib/textus/init.rb

@@ -6,7 +6,7 @@ module Textus
     ZONES = %w[knowledge notebook proposals artifacts raw].freeze
 
     DEFAULT_MANIFEST = <<~YAML
-      version: textus/3
+      version: textus/4
       roles:
         - { name: human,      can: [author, propose] }
         - { name: agent,      can: [propose, keep] }
@@ -42,8 +42,8 @@ module Textus
         path: data/artifacts/derived/orientation.json
         lane: artifacts
         publish:
-        - { to: CLAUDE.md, template: orientation.mustache, inject_boot: true }
-        - { to: AGENTS.md, template: orientation.mustache, inject_boot: true }
+        - { to: CLAUDE.md, template: orientation.erb, inject_boot: true }
+        - { to: AGENTS.md, template: orientation.erb, inject_boot: true }
         kind: produced
     YAML
 
@@ -93,7 +93,7 @@ module Textus
 
     def self.setup_state_dirs(target_root)
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
-      FileUtils.mkdir_p(Textus::Layout.state(target_root))
+      FileUtils.mkdir_p(Textus::Layout.cursors(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
     end
 
@@ -121,7 +121,7 @@ module Textus
       {
         "project.schema.yaml" => File.join("schemas", "project.yaml"),
         "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
-        "orientation.mustache" => File.join("templates", "orientation.mustache"),
+        "orientation.erb" => File.join("templates", "orientation.erb"),
       }.each do |src, dest|
         File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
       end