textus

CI Gem Version Ruby License

A context store for codebases that humans and AI agents both have to read and write. Dotted keys, schema-validated entries, role-gated writes, byte-copy publish, an audit log of every change. Built so an agent landing in your repo can run one command (textus intro) and know what to read, what to write, and what's off-limits.

Reference implementation in Ruby. Wire format textus/2. SPEC: SPEC.md. Implementation notes: docs/.

Versioning

Two versions, deliberately independent:

  • Protocol wire string: textus/2. Stable; breaking changes require textus/3.
  • Gem version: semver, currently 0.10.3. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.

Envelope payloads carry the protocol field. The gem version is irrelevant to the wire format.

Install

gem install textus

Or from this repo:

bundle install
bundle exec exe/textus --help

Quick start

textus init

You get .textus/ with all five zone directories, baseline schemas, an empty audit log, and a starter manifest:

.textus/
  manifest.yaml       # zone declarations + key-to-path mapping
  audit.log           # append-only NDJSON, every write
  schemas/            # YAML field shapes per entry family
  templates/          # mustache templates for derived entries
  hooks/              # one .rb per hook
  sentinels/          # publish bookkeeping
  zones/
    identity/         # human-only — identity, voice, decisions
    working/          # human / ai / script — day-to-day catalog
    inbox/            # script — declared external inputs (actions)
    review/           # ai + human — proposals awaiting accept
    output/           # build only — computed outputs

Manifest path: fields are relative to .textus/zones/. So working.network.org.jane lives at .textus/zones/working/network/org/jane.md.

Read and write:

textus get working.network.org.jane
textus list --zone=working
echo '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
  | textus put working.network.org.bob --as=human --stdin
textus freshness --zone=output       # per-entry fresh/stale/never_refreshed/no_policy
textus policy list                   # show every policy block
textus audit --limit=20              # query the audit log

(All verbs return JSON envelopes by default; pass --format=json explicitly if you prefer.)

For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see examples/claude-plugin/.

What ships today

  • Per-entry formats. format: markdown | json | yaml | text on a manifest entry. cat .textus/zones/output/marketplace.json | jq . works without going through textus — the in-store file is the consumer-shaped artifact. Structured outputs carry _meta at the top level (generated_at, from, template, reducer).
  • Per-leaf publishing. Nested entries declare publish_each: "skills/{basename}/SKILL.md". Every leaf byte-copies to its consumer location on textus build. No more hand-mirrored agents/ / skills/ / commands/ directories.
  • Stable identity (uid:). 16-char hex, auto-minted on first put, preserved across writes and moves. textus key mv old.key new.key renames in place — uid survives, audit row records from_key, to_key, uid. Reorganising a tree no longer breaks references.
  • Strict key grammar. /^[a-z0-9][a-z0-9-]*$/, max 8 segments × 64 chars. textus key migrate --dry-run|--write rewrites existing stores with illegal segments deterministically.
  • textus intro. One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
  • textus doctor. Health check across 9 categories: missing schemas/templates, broken hooks, illegal nested keys, sentinel drift, audit log readability, unowned schema fields, schema violations, and missing manifest files. Returns ok: true only when nothing is wrong; warnings and info don't flip the bit.
  • Actionable hints on every error. UnknownKey carries ranked "did you mean" suggestions. WriteForbidden names the role that would be allowed. BadFrontmatter tells you exactly what to rename. Printed to stderr alongside the JSON envelope on stdout.

Symlink-mode publish was removed; publish is FileUtils.cp + sentinel. Sentinels for published files live under .textus/sentinels/<target_rel>.textus-managed.json so consumer directories stay clean. Legacy sibling sentinels auto-migrate on next publish.

CLI and zones

All verbs accept --format=json and return the envelope defined in SPEC §8. Write verbs require --as=<role> (role resolution: --as → TEXTUS_ROLE env → .textus/role file → default human).

  • Full verb table — read, write, health, scaffolding — is in SPEC §9.
  • Zone semantics and the role/writable_by mapping live in SPEC §5, with a tutorial expansion in docs/zones.md.

textus intro prints the same information for the current store: zones, entry families with schemas, registered hooks, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.

Compute and publish

Derived entries declare a projection: (select, pluck, sort_by, limit, optional reducer) and either a template under .textus/templates/ (markdown/text) or a templateless path that lets a reducer shape the output directly (json/yaml). Projections cap at 1000 rows; the vendored Mustache subset caps at depth 8. No partials, no lambdas, no HTML escaping.

publish_to: [path] byte-copies a single derived file to one target. publish_each: "template/{basename}.md" on a nested entry byte-copies every leaf to its templated target — substitutes {leaf}, {basename}, {key}, {ext}. Sentinels for every published file live under .textus/sentinels/. See SPEC §5.2, §5.3, §5.12.

Extension points

textus exposes a hook DSL. Drop .rb files into .textus/hooks/ (subdirectories are fine; files load alphabetically by full path). Events:

  • :intake — bring bytes in from elsewhere (returns {_meta:, body:})
  • :reduce — transform rows during projection (returns rows)
  • :check — custom doctor check (returns issues)
  • :put, :deleted, :refreshed, :built, :accepted, :published, :mv, :reject, :loaded — react to lifecycle events
  • :refresh_began, :refresh_failed, :refresh_detached — background-refresh lifecycle
# Inside .textus/hooks/local_file.rb
Textus.intake(:local_file) do |config:, args:, **|
  path = config["path"] or raise "local-file requires intake.config.path"
  {
    _meta: { "last_refreshed_at" => Time.now.utc.iso8601, "source_path" => path },
    body: File.read(File.expand_path(path)),
  }
end

Textus.reduce(:rank_by_recency) do |rows:, **|
  rows.sort_by { |r| r["updated_at"].to_s }.reverse
end

To keep a batch of stale intake entries current in one shot:

textus refresh-stale --prefix=working --zone=inbox --as=script
# or just refresh everything stale in the inbox zone:
textus refresh-stale --zone=inbox --as=script

The primitive Textus.hook(event, name, **opts) { ... } is also supported. See SPEC.md §5.10 for the full contract.

Schemas (.textus/schemas/<name>.yaml) declare field shapes, per-field maintained_by: ownership, and an evolution: block (added_in, deprecated_at, migrate_from). Full contract in SPEC §5.8.

Examples

examples/claude-plugin/ — a Claude Code plugin (voice-tools) whose entire content surface — agents, skills, commands, CLAUDE.md, plugin.json, marketplace.json — is textus-managed. Demonstrates per-entry formats, publish_each, intake actions, in-process reducers and hooks, the AI-propose / human-accept loop, and the inject_intro: flag that puts an orientation preamble at the top of CLAUDE.md.

Tests

bundle exec rspec

~490 examples; includes conformance fixtures A–I from SPEC §12.

Code quality

bundle exec rubocop      # lint
bundle exec rubocop -A   # lint + autocorrect

Lefthook hooks (brew bundle install then lefthook install) run rubocop on pre-commit and rspec + rubocop on pre-push. Bypass with LEFTHOOK=0 git commit ... when needed. CI runs rspec (Ruby 3.3 / 3.4) and rubocop via GitHub Actions.

License

MIT.