textus 0.39.0 → 0.39.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15b2e8bcfb3e83425617ee187705b88ad99c1f96671a7ad04a8394073f98065d
-  data.tar.gz: e0711f287c8739fcc2e5f9507fd5637b9c63159b2d8e364f9d65f338138ff432
+  metadata.gz: af15d8a77f0d71c3fab21dc246545b3a7b84242361c518b1d901c491c63e55c4
+  data.tar.gz: 4644479ed6df331a6973806fed302b29446d3806d1793d8ea9d9fa661000e986
 SHA512:
-  metadata.gz: 74ec9edba22fdd7884c7bf1a16b9f73a636524c11f889824a516775857294ea674ebd6f6fe9b0a4d98028d30cf5673b51c376760968baa4d8413c83a33475484
-  data.tar.gz: c097ccd942039828754bd70ae2f457e172ca88166c318c72199138e126301aa4432cec318ff77c456a73de4176c0e6fe65160cca899111dcd27785adc9eff62c
+  metadata.gz: ee1cf4024e3583c1e59791b279a2fd0f8c00e426f05391267db0239d1a7d2909c521b94bc27caf62d549d902b0dc7f62847178f0ea17973e14b26689a981302a
+  data.tar.gz: 775daa6d3992b0b93d2a57c230fbfc5705b50fec592327356f4fa6ccc4dc39aaacdcbd1c24d2dd878a1b6612fd5e9c3416ede0b42d9ba90978dc8f8461c6d014

data/CHANGELOG.md

@@ -11,6 +11,35 @@ tracks both additive improvements and breaking protocol bumps independently.
 
 ## Unreleased
 
+## 0.39.1 — 2026-06-01 — Feed ergonomics: `feeds.machine` env snapshot + intake cookbook ([ADR 0043](docs/architecture/decisions/0043-feed-ergonomics-without-breaking-core-purity.md))
+
+No `textus/3` wire-format change. `textus init` scaffolds an additional
+`nested` feed entry; core intake still makes no implicit network calls
+(SPEC §5.4).
+
+### Added
+
+- **`textus init` scaffolds `feeds.machines.*` with a local env snapshot
+  (ADR 0043).** Generated stores get a `nested` feed entry capturing ambient
+  machine context (git HEAD/branch/dirty state, `now`, versions) as an explicit,
+  user-owned snapshot — keeping ambient state out of `boot`/`pulse` (which stay
+  side-effect-free per ADR 0037) and out of `quarantine` (which means external
+  bytes pending validation, where the freshness model does not apply).
+
+### Documentation
+
+- **Multi-machine environment-scan cookbook recipe** demonstrating the nested
+  `feeds.machines.*` pattern.
+- **Examples** updated to use the `feeds.machine` env snapshot, matching
+  `textus init` output.
+- **README flow diagram** redesigned to group writers and colour-code roles.
+- **How-to fixes** for zone-rename drift in the agents-mcp guide and the
+  `:publish` event name.
+
+### Internal
+
+- Removed the legacy `ARCHITECTURE.md` redirect stub.
+
 ## 0.39.0 — 2026-06-01 — Native ignore patterns for entry enumeration ([ADR 0042](docs/architecture/decisions/0042-native-ignore-patterns-for-entry-enumeration.md))
 
 No `textus/3` wire-format change. Manifest schema gains one optional, backward-compatible key (`ignore:`); existing manifests are unaffected.

data/README.md

@@ -27,20 +27,33 @@ Three actors write to your repo today:
 
 ```mermaid
 flowchart LR
-    human(["human"]) -->|author| knowledge["knowledge<br/>(canon)"]
-    agent(["agent"]) -->|keep| notebook["notebook<br/>(workspace)"]
+    subgraph writers["writers — who can write"]
+        direction TB
+        human(["human"])
+        agent(["agent"])
+        automation(["automation"])
+    end
+
+    human -->|author| knowledge["knowledge<br/>(canon)"]
+    agent -->|keep| notebook["notebook<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
-    proposals ==>|human accept| knowledge
-    automation(["automation"]) -->|fetch| feeds["feeds<br/>(quarantine)"]
+    automation -->|fetch| feeds["feeds<br/>(quarantine)"]
     automation -->|build| artifacts["artifacts<br/>(derived)"]
+
+    proposals ==>|human accept| knowledge
     feeds -.->|projection source| artifacts
     knowledge -.->|projection source| artifacts
 
-    classDef anchor fill:#1f6feb,stroke:#1f6feb,color:#fff;
+    classDef actor fill:#238636,stroke:#2ea043,color:#fff;
+    classDef gate fill:#9e6a03,stroke:#bb8009,color:#fff;
+    classDef anchor fill:#1f6feb,stroke:#388bfd,color:#fff;
+    class human,agent,automation actor;
+    class proposals gate;
     class knowledge anchor;
 ```
 
 *Each actor writes only into its own lane; low-trust input climbs to authoritative lanes only by passing a guarded transition (an agent's proposal needs a human `accept`).*
+*Colour legend: **green** = writers · **amber** = the review gate (`proposals`) · **blue** = the trust anchor (`knowledge`).*
 
 The point of those lanes is to **build context you can trust**. Place each lane on two axes — how durable it is, and how much you can rely on it without review — and the value shows up as a climb: the high-trust corner (durable *and* authoritative = `knowledge`) is the one place nothing is *written* directly. It's *earned* by crossing the `accept` gate.
 

data/lib/textus/init/templates/machine_intake.rb

@@ -0,0 +1,45 @@
+# .textus/hooks/machine_intake.rb
+# Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
+# entry from manifest.yaml if you don't want it.
+# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus fetch` (never
+# on the per-turn boot/pulse path). It is NESTED so it grows to a fleet: the
+# `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
+# (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an
+# ALLOWLIST of versions and counts — NEVER secrets, raw `env`, or package lists.
+Textus.hook do |reg|
+  reg.on(:resolve_intake, :machines) do |config:, args:, **|
+    machine = args[:leaf_segments].first or
+      raise "fetch a host leaf, e.g. `textus fetch feeds.machines.local`"
+    spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
+    unless (spec["via"] || "local").to_s == "local"
+      raise "machine #{machine}: only `via: local` is scaffolded — see " \
+            "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
+    end
+
+    sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
+    ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
+    count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
+    { content: {
+      # git_* describe THIS repo on the control host — only meaningful for `local`.
+      "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
+      "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
+      "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
+      "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
+      "captured_at"    => Time.now.utc.iso8601,
+      "os"             => RbConfig::CONFIG["host_os"],
+      "arch"           => RbConfig::CONFIG["host_cpu"],
+      "ruby_version"   => RUBY_VERSION,
+      "runtimes"       => {                                 # versions only; nil when not installed
+        "node"   => ver.call("node --version"),
+        "python" => ver.call("python3 --version"),
+        "go"     => ver.call("go version"),
+      },
+      "packages"       => {                                 # COUNTS only — never the list (size/secrets)
+        "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
+        "apt"  => count.call("dpkg-query -f '.\n' -W"),
+      },
+      "textus_version" => Textus::VERSION,
+      "protocol"       => Textus::PROTOCOL,
+    } }
+  end
+end

data/lib/textus/init.rb

@@ -1,4 +1,5 @@
 require "fileutils"
+require "pathname"
 
 module Textus
   module Init
@@ -21,6 +22,26 @@ module Textus
         - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
         - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
         - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
+        # A per-host snapshot, pulled by `textus fetch feeds.machines.local --as=automation`.
+        # Nested so it grows to a fleet — add feeds.machines.<host> leaves over SSH
+        # (see docs/cookbook/environment-scan.md) without renaming. tracked:false →
+        # gitignored (machine info can be sensitive/noisy) but still protocol-readable
+        # via `textus get feeds.machines.local`. Delete to opt out. (ADR 0043)
+        - key: feeds.machines
+          path: feeds/machines
+          zone: feeds
+          format: yaml
+          nested: true
+          tracked: false
+          kind: intake
+          intake:
+            handler: machines
+            config:
+              machines:
+                local: { via: local }
+      rules:
+        - match: feeds.machines.**
+          fetch: { ttl: 1h, on_stale: warn } # meaningful on a long-running server
     YAML
 
     HOOKS_README = <<~MD
@@ -91,12 +112,31 @@ module Textus
         File.write(File.join(dir, ".gitkeep"), "")
       end
       File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
+      scaffold_dir = File.expand_path("init/templates", __dir__)
+      File.write(File.join(target_root, "hooks", "machine_intake.rb"),
+                 File.read(File.join(scaffold_dir, "machine_intake.rb")))
       File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
       FileUtils.mkdir_p(Textus::Layout.state(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
-      File.write(File.join(target_root, ".gitignore"), Textus::Layout::GITIGNORE)
+      File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
       { "protocol" => PROTOCOL, "initialized" => target_root }
     end
+
+    # The store's `.gitignore` is generated, never hand-kept (ADR 0038), and now
+    # derived from the manifest: the run subtree plus every `tracked: false`
+    # entry's resolved path (ADR 0043).
+    def self.derived_gitignore(target_root)
+      manifest = Textus::Manifest.load(target_root)
+      root = Pathname.new(target_root)
+      untracked = manifest.data.entries.reject(&:tracked?).map do |e|
+        if e.nested? # a whole subtree of leaf files (feeds.machines.* → zones/feeds/machines/)
+          "#{File.join("zones", e.path)}/"
+        else
+          Pathname.new(Textus::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
+        end
+      end
+      Textus::Layout.gitignore_body(untracked_paths: untracked)
+    end
   end
 end

data/lib/textus/layout.rb

@@ -33,9 +33,22 @@ module Textus
       File.join(audit_dir(root), "audit.log")
     end
 
-    GITIGNORE = <<~GITIGNORE
-      # textus runtime artifacts — safe to delete, never commit
-      #{RUN}/
-    GITIGNORE
+    # The store's `.gitignore` body. Always ignores the runtime subtree
+    # (`.run/`, ADR 0038); when given untracked entry paths (entries marked
+    # `tracked: false`), it also lists those so they stay protocol-readable but
+    # uncommitted (ADR 0043, refining 0038). Generated, never hand-kept — no
+    # drift between the manifest and the ignore file.
+    def self.gitignore_body(untracked_paths: [])
+      lines = ["# textus runtime artifacts — safe to delete, never commit",
+               "#{RUN}/"]
+      unless untracked_paths.empty?
+        lines << "# tracked:false entries — protocol-readable, not committed (sensitive)"
+        lines.concat(untracked_paths)
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    # Back-compat constant: the no-untracked-entries body (just the run subtree).
+    GITIGNORE = gitignore_body
   end
 end

data/lib/textus/manifest/entry/base.rb

@@ -31,6 +31,12 @@ module Textus
         def intake?  = false
         def leaf?    = false
 
+        # Whether git should track this entry's file. Default true; an entry
+        # marked `tracked: false` in the manifest stays protocol-readable but is
+        # listed in the generated `.gitignore` (ADR 0043). Cross-cutting, so it
+        # reads from raw here rather than threading through every constructor.
+        def tracked? = @raw["tracked"] != false
+
         # Nil stubs for cross-cutting optional attrs. Subclasses override the
         # ones they own. Validators and serializers can call these directly
         # without `respond_to?` guards.

data/lib/textus/manifest/schema.rb

@@ -25,7 +25,7 @@ module Textus
       ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
         compute template publish_to publish_each
-        intake events inject_boot index_filename ignore
+        intake events inject_boot index_filename ignore tracked
       ].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.39.0"
+  VERSION = "0.39.1"
   PROTOCOL = "textus/3"
 end

data/lib/textus.rb

@@ -17,6 +17,10 @@ loader.inflector.inflect(
 loader.ignore(File.expand_path("textus/errors.rb", __dir__))
 loader.ignore(File.expand_path("textus/mcp.rb", __dir__))
 loader.ignore(File.expand_path("textus/mcp/errors.rb", __dir__))
+# Scaffold sources copied verbatim into user stores by `textus init`. They are
+# file templates (one calls `Textus.hook` at load time), not gem constants —
+# Zeitwerk must not manage or eager-load them (ADR 0043).
+loader.ignore(File.expand_path("textus/init/templates", __dir__))
 loader.setup
 loader.eager_load
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.39.1
 platform: ruby
 authors:
 - Patrick
@@ -103,7 +103,6 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ARCHITECTURE.md
 - CHANGELOG.md
 - README.md
 - SPEC.md
@@ -234,6 +233,7 @@ files:
 - lib/textus/hooks/rpc_registry.rb
 - lib/textus/hooks/signature.rb
 - lib/textus/init.rb
+- lib/textus/init/templates/machine_intake.rb
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.rb

data/ARCHITECTURE.md

@@ -1,3 +0,0 @@
-# Architecture
-
-Moved to [`docs/architecture/README.md`](docs/architecture/README.md).