intent-record 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 871b5d799ddc9505ac23dbbd3bf468d243ae3c48a4c04574e9fd0fc596a579ae
+  data.tar.gz: f6370c0f8003d35971d1b717c1ca7d24632b38b9568496c22e7605838397f9d6
+SHA512:
+  metadata.gz: 7d0ef27f3db2d4bf6616ea46f225462e778dad93c6433738d90f03e7c68fac5c2ee196681f1445a15673915d5ac449f0737d12974d01af97cdb618a4530f2759
+  data.tar.gz: 5dc2d7077843e89318b6d8d5ef7238663eb531e8ab01633a63f7a40c96f025577751e2a757f27fa64e8e1c31a81eef4ca9c8829d818fdd0f4bffbb1faa61867a

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Notable changes, one section per released version. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 1.0.0 - 2026-09-18
+
+First release.
+
+- `record`, `attach`, `show`, `lookup`, `search`, `by-source`, `recent`, `systems` and `serve`. JSON in on stdin, JSON out on stdout, exit 1 with `{"error": ...}` on failure. Argv a command does not recognise is refused rather than ignored.
+- SQLite store at `~/.intent-record/`, created and migrated on first use. `--config-dir` points one command at another store, `INTENT_RECORD_CONFIG_DIR` points a whole shell at one.
+- An intent links to any number of commits, to stakeholder sources such as Jira, Confluence and Linear, and to earlier intents it builds on. Commits can be attached after the fact, which covers rebases and squashes.
+- Prefix lookup from four characters for hash-based systems. An id recorded in two systems is reported as ambiguous rather than answered with one of them.
+- Every list comes back in an order the query names, in both the CLI and the GUI.
+- Local web GUI on 127.0.0.1 with commit, intent, search and stakeholder source pages.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik T. Madsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# intent-record
+
+[![CI](https://github.com/beatmadsen/intent-record/actions/workflows/ci.yml/badge.svg)](https://github.com/beatmadsen/intent-record/actions/workflows/ci.yml)
+
+Local records storage for the intent behind individual code changes.
+
+A commit message says what changed. The intent record says why: what the agent (or person) was trying to achieve, which ticket or design page asked for it, and which earlier change it builds on. intent-record stores that in a local SQLite database, links it to the commit hash, and answers the questions people and agents ask later.
+
+- "What was this commit for?" (`lookup <hash>`)
+- "What did we build for this Jira ticket, and why that way?" (`by-source <url-or-key>`)
+- "Have we touched retry logic before, and what were we thinking?" (`search retry`)
+
+## Installation
+
+```bash
+gem install intent-record
+```
+
+On first run a config directory is created at `~/.intent-record/` with the database at `~/.intent-record/intent-record.db`. Edit `~/.intent-record/config.yml` to move the database.
+
+To use a different store for one command, pass `--config-dir <dir>` before or after the command name. `INTENT_RECORD_CONFIG_DIR` does the same for a whole shell, except that a misspelled variable name is ignored without a word while a misspelled flag is refused.
+
+```bash
+intent-record --config-dir /tmp/scratch recent
+```
+
+## Quick start
+
+```bash
+# After committing a change, record why it was made
+echo '{
+  "summary": "Retry flaky fetches with backoff",
+  "body": "CI failed three times this week on transient DNS errors. Retrying 3x with exponential backoff instead of failing the build.",
+  "author": "claude",
+  "commits": ["8f3a1c2d9e4b5f60718293a4b5c6d7e8f9a0b1c2"],
+  "stakeholder_references": [
+    {"system": "jira", "uri": "https://acme.atlassian.net/browse/ACME-42", "title": "Flaky fetch in CI"}
+  ]
+}' | intent-record record
+# => {"intent_id":"EUt4WMY","summary":"Retry flaky fetches with backoff", ... full record ...}
+
+# Later, someone stares at that commit in git blame
+intent-record lookup 8f3a1c2
+
+# Or comes at it from the ticket
+intent-record by-source ACME-42 --contains
+
+# Or wants to read it in a browser
+intent-record serve
+```
+
+## Commands
+
+JSON in on stdin where input is needed, JSON out on stdout, exit code 0 on success and 1 with `{"error": "..."}` otherwise.
+
+| Command | Description |
+|---|---|
+| `record` | Record the intent behind a change (JSON via stdin) |
+| `attach <intent_id>` | Link more commits, stakeholder references or related intents to an existing record (JSON via stdin) |
+| `show <intent_id>` | Full intent record with commits, stakeholder links and related intents |
+| `lookup <commit> [--vcs name]` | All intents recorded against a commit. Accepts a full hash or a unique prefix of at least 4 characters. Ids are unique per system, not across them, so an id recorded in two systems is reported as ambiguous; name one with `--vcs` |
+| `search <terms...> [--match all]` | Case-insensitive substring search over summary, body, and linked stakeholder URIs and titles, so a ticket key finds its intents |
+| `by-source <uri> [--contains]` | Intents linked to a stakeholder source, plus the distinct commits across them. `--contains` matches a substring such as a ticket key |
+| `recent [--limit N]` | Newest intents first |
+| `systems` | Known VCS and stakeholder system names |
+| `serve [--port N]` | Start the web GUI on 127.0.0.1 (default port 4791) |
+
+### Input shape for `record` and `attach`
+
+```json
+{
+  "summary": "one line, at most 350 characters (record only, required)",
+  "body": "the reasoning, as long as it needs to be (record only, required)",
+  "author": "optional: agent or person name",
+  "commits": ["git hashes; shorthand for asset_versions with vcs git"],
+  "asset_versions": [{"vcs": "perforce", "external_id": "12345"}],
+  "stakeholder_references": [{"system": "jira", "uri": "https://...", "title": "optional"}],
+  "related_intent_ids": ["intent ids this change builds on"]
+}
+```
+
+Options take either `--name value` or `--name=value`. Unknown options and stray arguments are rejected rather than ignored.
+
+`lookup` without `--vcs` searches every system and prefers an exact id match over a prefix match. Git commits must be full SHA-1 or SHA-256 hashes; they are stored lowercase. Prefix lookup applies to hash-based systems only (git, mercurial, fossil, sapling, pijul, darcs), so a Perforce changelist `1234` never matches `12345`. URIs are normalised (lowercase scheme and host, no trailing slash) and system names are lowercased and hyphenated, so `Jira` and `jira`, or a ticket URL with and without a trailing slash, are one source. A later non-blank `title` for a source replaces the stored one.
+
+`record` and `attach` both return the full intent record. A record's commits, stakeholder references and related intents come back in the order they were attached.
+
+An intent can be recorded before the commit exists and linked with `attach` afterwards. This also covers rebases and squashes, where the same intent ends up on a new hash. One commit can carry several intents and one intent can span several commits.
+
+## Data model
+
+Commit hashes are treated as globally unique, so the store does not track which repository a commit belongs to. VCS and stakeholder system names are lowercased on the way in, and the common ones are seeded on first connect; `intent-record systems` lists them. Unknown names are added on first use.
+
+```
+vcs_systems            (name)
+asset_versions         (vcs_system, external_id)         a commit, changelist, revision
+intent_records         (global_id, summary, body, author)
+intent_record_asset_versions                             intent <-> asset version, many to many
+stakeholder_systems    (name)
+stakeholder_sources    (stakeholder_system, uri, title)  a ticket, page, thread
+stakeholder_references                                   intent <-> source, many to many
+intent_record_links    (source, target)                  intent builds on intent
+```
+
+Intent ids are random 7-character base58 strings. Database ids never appear in output.
+
+Related-intent links may form cycles; the store records what it is told and leaves the meaning to the reader. Bodies have no size cap.
+
+## Web GUI
+
+`intent-record serve` binds to localhost only. The home page has one box: paste a commit hash, a ticket URL, or a few words, and it takes you to the right page. Commit pages list every intent for that hash; source pages list every intent and every commit for a ticket.
+
+## Agent integration
+
+Any agent that can run a process and read stdout can use it. Record after each commit, `lookup` before touching unfamiliar code, `by-source` when picking up a ticket that has history.
+
+For Claude Code there is a skill that says when to do each of those and what a usable `body` contains: [intent-record](https://github.com/beatmadsen/claude-skills/tree/main/skills/intent-record), in the [beatmadsen/claude-skills](https://github.com/beatmadsen/claude-skills) collection. Install it for every project you work on:
+
+```bash
+git clone https://github.com/beatmadsen/claude-skills.git ~/claude-skills
+ln -s ~/claude-skills/skills/intent-record ~/.claude/skills/intent-record
+```
+
+Or copy `skills/intent-record` into a single project's `.claude/skills/` and commit it, so everyone working in that repository records the same way.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake        # tests, then the same tests with unordered queries reversed, then rubocop
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and release steps, and [CHANGELOG.md](CHANGELOG.md) for what changed in each version.
+
+## License
+
+[MIT](LICENSE.txt)

data/db/migrate/20260918000001_create_initial_schema.rb

@@ -0,0 +1,68 @@
+class CreateInitialSchema < ActiveRecord::Migration[8.0]
+  def change
+    create_table :vcs_systems do |t|
+      t.string :name, null: false
+      t.datetime :created_at, null: false
+    end
+    add_index :vcs_systems, :name, unique: true
+
+    create_table :asset_versions do |t|
+      t.references :vcs_system, null: false, foreign_key: true
+      t.string :external_id, null: false
+      t.datetime :created_at, null: false
+    end
+    add_index :asset_versions, %i[vcs_system_id external_id], unique: true
+    add_index :asset_versions, :external_id
+
+    create_table :intent_records do |t|
+      t.string :global_id, limit: 7, null: false
+      t.string :summary, null: false
+      t.text :body, null: false
+      t.string :author
+      t.datetime :created_at, null: false
+    end
+    add_index :intent_records, :global_id, unique: true
+    add_index :intent_records, :created_at
+
+    create_table :intent_record_asset_versions do |t|
+      t.references :intent_record, null: false, foreign_key: true
+      t.references :asset_version, null: false, foreign_key: true
+      t.datetime :created_at, null: false
+    end
+    add_index :intent_record_asset_versions, %i[intent_record_id asset_version_id],
+              unique: true, name: "idx_intent_asset_unique"
+
+    create_table :stakeholder_systems do |t|
+      t.string :name, null: false
+      t.datetime :created_at, null: false
+    end
+    add_index :stakeholder_systems, :name, unique: true
+
+    create_table :stakeholder_sources do |t|
+      t.references :stakeholder_system, null: false, foreign_key: true
+      t.text :uri, null: false
+      t.string :title
+      t.datetime :created_at, null: false
+    end
+    add_index :stakeholder_sources, %i[stakeholder_system_id uri], unique: true
+
+    create_table :stakeholder_references do |t|
+      t.references :intent_record, null: false, foreign_key: true
+      t.references :stakeholder_source, null: false, foreign_key: true
+      t.datetime :created_at, null: false
+    end
+    add_index :stakeholder_references, %i[intent_record_id stakeholder_source_id],
+              unique: true, name: "idx_stakeholder_ref_unique"
+
+    create_table :intent_record_links do |t|
+      t.bigint :source_intent_record_id, null: false
+      t.bigint :target_intent_record_id, null: false
+      t.datetime :created_at, null: false
+    end
+    add_index :intent_record_links, %i[source_intent_record_id target_intent_record_id],
+              unique: true, name: "idx_intent_link_unique"
+    add_index :intent_record_links, :target_intent_record_id
+    add_foreign_key :intent_record_links, :intent_records, column: :source_intent_record_id
+    add_foreign_key :intent_record_links, :intent_records, column: :target_intent_record_id
+  end
+end

data/exe/intent-record

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "intent_record"
+
+IntentRecord::CLI.run(ARGV)

data/lib/intent_record/application_record.rb

@@ -0,0 +1,8 @@
+require "active_record"
+
+module IntentRecord
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name_prefix = ""
+  end
+end

data/lib/intent_record/asset_version_normalizer.rb

@@ -0,0 +1,43 @@
+module IntentRecord
+  # Normalises external ids per VCS. Hash-based systems store their ids lowercased and
+  # support prefix lookup. Only git is checked for shape, and must be a full SHA-1 or
+  # SHA-256; the other hash-based systems take an id as given, so a prefix among those
+  # can collide, and the resolver reports that at lookup time rather than preventing it
+  # here.
+  module AssetVersionNormalizer
+    HASH_BASED = %w[git mercurial fossil sapling pijul darcs].freeze
+    GIT_HASH = /\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/
+
+    module_function
+
+    def vcs_name(vcs)
+      vcs.strip.downcase
+    end
+
+    def hash_based?(vcs)
+      HASH_BASED.include?(vcs)
+    end
+
+    def external_id(vcs, raw)
+      id = raw.strip
+      id = id.downcase if hash_based?(vcs)
+      if vcs == "git" && !GIT_HASH.match?(id)
+        raise ValidationError,
+              "git commit must be 40 or 64 hex characters, got #{raw.inspect}"
+      end
+
+      id
+    end
+
+    # Hash ids are canonically lowercase here, and that should not depend on a
+    # collation default we do not set. Nothing driving the CLI can tell this apart
+    # from leaving the id alone, because the resolver tries the id as written too
+    # and sqlite's LIKE folds ASCII case; the tests that decide it ask this
+    # directly, or go through the resolver below the prefix minimum, where there
+    # is no second chance from the prefix query.
+    def lookup_id(vcs, raw)
+      id = raw.strip
+      vcs.nil? || hash_based?(vcs) ? id.downcase : id
+    end
+  end
+end

data/lib/intent_record/asset_version_resolver.rb

@@ -0,0 +1,76 @@
+require_relative "models/asset_version"
+require_relative "models/vcs_system"
+require_relative "asset_version_normalizer"
+require_relative "like_pattern"
+
+module IntentRecord
+  # Resolves an external id to one asset version. Exact match first; for hash-based VCSs a
+  # unique prefix of at least MIN_PREFIX_LENGTH characters also resolves.
+  class AssetVersionResolver
+    MIN_PREFIX_LENGTH = 4
+
+    def initialize(external_id:, vcs: nil)
+      @vcs = vcs && AssetVersionNormalizer.vcs_name(vcs)
+      @raw = external_id.strip
+      @external_id = AssetVersionNormalizer.lookup_id(@vcs, external_id)
+    end
+
+    def call
+      exact_match || resolve_prefix
+    end
+
+    private
+
+    # With no vcs given the id could belong to a hash-based system, where case is
+    # insignificant, or to a case-sensitive one, where it is not, so both spellings
+    # are candidates. When a vcs is given the normaliser has already picked the one
+    # that system uses.
+    def exact_candidates
+      @vcs ? [@external_id] : [@raw, @external_id].uniq
+    end
+
+    # Ids are unique per version control system, not across them, so one spelling
+    # can name two different things. Answering with either of them would be
+    # SQLite's choice, and it would hide everything recorded against the other,
+    # so say so instead and let the caller name the system.
+    def exact_match
+      exact_candidates.each do |id|
+        found = scope.where(external_id: id).to_a
+        next if found.empty?
+        raise ValidationError, ambiguous(id, found.size) if found.size > 1
+
+        return found.first
+      end
+      nil
+    end
+
+    def ambiguous(id, count)
+      "Ambiguous id #{id}: matches #{count} asset versions in different " \
+        "version control systems. Name one with --vcs."
+    end
+
+    def resolve_prefix
+      candidates = prefix_candidates
+      raise NotFoundError, "Asset version not found: #{@external_id}" if candidates.empty?
+      if candidates.size > 1
+        raise ValidationError,
+              "Ambiguous prefix #{@external_id}: matches #{candidates.size} asset versions"
+      end
+
+      candidates.first
+    end
+
+    def scope
+      base = Models::AssetVersion.includes(:vcs_system).joins(:vcs_system)
+      @vcs ? base.where(vcs_systems: { name: @vcs }) : base
+    end
+
+    def prefix_candidates
+      return [] if @external_id.length < MIN_PREFIX_LENGTH
+
+      scope.where(vcs_systems: { name: AssetVersionNormalizer::HASH_BASED })
+           .where(LikePattern.prefix("asset_versions.external_id"), LikePattern.prefix_bind(@external_id))
+           .to_a
+    end
+  end
+end

data/lib/intent_record/cli/argv_parser.rb

@@ -0,0 +1,78 @@
+module IntentRecord
+  class CLI
+    # Owns the arguments it is given and consumes them: each `take_*` removes what
+    # it matched, so `reject_leftovers!` can then judge whatever nobody claimed.
+    # The caller's own array is never touched. Options may be given as
+    # `--name value` or `--name=value`.
+    class ArgvParser
+      def initialize(argv)
+        @argv = argv.dup
+      end
+
+      # What is left unconsumed, for a caller that forwards its arguments on
+      # rather than judging them here.
+      def remaining
+        @argv.dup
+      end
+
+      def take_flag(name)
+        indexes = @argv.each_index.select { |i| @argv[i] == name || @argv[i].start_with?("#{name}=") }
+        raise ValidationError, "#{name} given more than once" if indexes.size > 1
+        return nil if indexes.empty?
+
+        extract_flag(indexes.first, name)
+      end
+
+      def take_integer_flag(name, default)
+        raw = take_flag(name)
+        return default if raw.nil?
+        raise ValidationError, "#{name} requires an integer, got #{raw.inspect}" unless /\A\d+\z/.match?(raw)
+
+        raw.to_i
+      end
+
+      # Judged by its stripped form, so returned stripped too. Handing back the
+      # padded value let a command look an id up verbatim and miss a record that
+      # exists.
+      def take_required_positional(label)
+        value = @argv.shift
+        raise ValidationError, "#{label} is required" if value.nil? || value.strip.empty?
+
+        value.strip
+      end
+
+      # Everything that is not an option. The options are kept, so
+      # reject_leftovers! still judges them.
+      def take_positionals
+        options, positionals = @argv.partition { |token| token.start_with?("--") }
+        @argv.replace(options)
+        positionals
+      end
+
+      def take_switch?(name)
+        !@argv.delete(name).nil?
+      end
+
+      def reject_leftovers!
+        return if @argv.empty?
+
+        raise ValidationError, "Unexpected argument(s): #{@argv.join(" ")}"
+      end
+
+      private
+
+      # A flag whose value is missing is deliberately left in place rather than
+      # consumed, so that it reaches reject_leftovers! as an error instead of
+      # passing for a value nobody gave.
+      def extract_flag(idx, name)
+        token = @argv[idx]
+        return @argv.delete_at(idx).delete_prefix("#{name}=") if token.include?("=")
+        return nil unless @argv[idx + 1] && !@argv[idx + 1].start_with?("--")
+
+        value = @argv[idx + 1]
+        @argv.slice!(idx, 2)
+        value
+      end
+    end
+  end
+end

data/lib/intent_record/cli/dispatch.rb

@@ -0,0 +1,118 @@
+require "json"
+require_relative "argv_parser"
+require_relative "stdin_json"
+require_relative "usage"
+require_relative "../commands/record"
+require_relative "../commands/show"
+require_relative "../commands/lookup"
+require_relative "../commands/search"
+require_relative "../commands/by_source"
+require_relative "../commands/recent"
+require_relative "../commands/attach"
+require_relative "../commands/systems"
+
+module IntentRecord
+  class CLI
+    # Maps a command name to the command object that handles it and prints its JSON result.
+    # Each run_* parses argv fully, then `finish!` rejects anything left over before running.
+    class Dispatch
+      HANDLER_PREFIX = "run_".freeze
+
+      # The commands there are, taken from the handlers that implement them, so
+      # the list cannot fall behind what the dispatch actually answers to.
+      def self.commands
+        handlers = private_instance_methods(false).grep(/\A#{HANDLER_PREFIX}/)
+        handlers.map { |name| name.to_s.delete_prefix(HANDLER_PREFIX).tr("_", "-") }.sort
+      end
+
+      def initialize(argv, streams:, config:)
+        @parser = ArgvParser.new(argv)
+        @streams = streams
+        @config = config
+      end
+
+      def call(command)
+        handler = "#{HANDLER_PREFIX}#{command.to_s.tr("-", "_")}"
+        raise ValidationError, unknown(command) unless respond_to?(handler, true)
+
+        emit(send(handler))
+      end
+
+      private
+
+      # An option in the command's place is almost always a misspelled one, and
+      # calling it an unknown command sends the reader looking for a command they
+      # never meant to type.
+      def unknown(command)
+        return "Unknown option: #{command}" if command.to_s.start_with?("--")
+
+        "Unknown command: #{command}. Known commands: #{self.class.commands.join(", ")}"
+      end
+
+      def emit(result)
+        @streams.stdout.puts JSON.generate(result)
+        0
+      end
+
+      def finish!
+        @parser.reject_leftovers!
+        yield
+      end
+
+      def stdin_json
+        StdinJson.read(@streams.stdin)
+      end
+
+      def positional(label)
+        @parser.take_required_positional(label)
+      end
+
+      def run_record
+        finish! { Commands::Record.new.call(stdin_json) }
+      end
+
+      def run_show
+        command = Commands::Show.new(intent_id: positional("intent_id"))
+        finish! { command.call }
+      end
+
+      def run_lookup
+        vcs = @parser.take_flag("--vcs")
+        command = Commands::Lookup.new(external_id: positional("external_id"), vcs: vcs)
+        finish! { command.call }
+      end
+
+      def run_search
+        match = @parser.take_flag("--match") || "any"
+        terms = @parser.take_positionals
+        finish! { Commands::Search.new(terms: terms, match: match).call }
+      end
+
+      def run_by_source
+        contains = @parser.take_switch?("--contains")
+        command = Commands::BySource.new(uri: positional("uri"), contains: contains)
+        finish! { command.call }
+      end
+
+      def run_recent
+        limit = @parser.take_integer_flag("--limit", Commands::Recent::DEFAULT_LIMIT)
+        finish! { Commands::Recent.new(limit: limit).call }
+      end
+
+      def run_attach
+        command = Commands::Attach.new(intent_id: positional("intent_id"))
+        finish! { command.call(stdin_json) }
+      end
+
+      def run_systems
+        finish! { Commands::Systems.new.call }
+      end
+
+      def run_serve
+        require_relative "../web/boot"
+        Web::Boot.run!(config: @config, argv: @parser.remaining, streams: @streams)
+        {}
+      end
+    end
+  end
+end

data/lib/intent_record/cli/stdin_json.rb

@@ -0,0 +1,28 @@
+require "json"
+
+module IntentRecord
+  class CLI
+    # The JSON object an agent sends on stdin. Nothing here concerns argv, which
+    # is why it is not in ArgvParser.
+    module StdinJson
+      module_function
+
+      def read(stdin)
+        raw = stdin.read.to_s.dup.force_encoding(Encoding::UTF_8)
+        raise ValidationError, "Input is not valid UTF-8" unless raw.valid_encoding?
+        raise ValidationError, "Empty input" if raw.strip.empty?
+
+        parse_object(raw)
+      end
+
+      def parse_object(raw)
+        parsed = JSON.parse(raw)
+        raise ValidationError, "Input must be a JSON object" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise ValidationError, "Invalid JSON input: #{e.message}"
+      end
+    end
+  end
+end

data/lib/intent_record/cli/streams.rb

@@ -0,0 +1,9 @@
+module IntentRecord
+  class CLI
+    Streams = Struct.new(:stdin, :stdout, :stderr, keyword_init: true) do
+      def self.default
+        new(stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      end
+    end
+  end
+end

data/lib/intent_record/cli/usage.rb

@@ -0,0 +1,29 @@
+module IntentRecord
+  class CLI
+    USAGE = <<~USAGE.freeze
+      Usage: intent-record <command> [options]
+
+      Commands:
+        record                          Record the intent behind a change (JSON via stdin)
+        attach <intent_id>              Link more commits / stakeholder refs / related intents (JSON via stdin)
+        show <intent_id>                Full intent record
+        lookup <commit> [--vcs name]    Intents recorded against a commit (full hash or unique prefix)
+        search <terms...> [--match all] Substring search over summary and body
+        by-source <uri> [--contains]    Intents linked to a stakeholder uri (Jira ticket, Confluence page, ...)
+        recent [--limit N]              Newest intents first
+        systems                         Known vcs and stakeholder system names
+        serve [--port N]                Start the local web GUI
+
+      Options:
+        --config-dir <dir>              Use the store in this directory instead of ~/.intent-record
+        --help, -h                      Show this help
+        --version                       Show version
+
+      Input shape for record/attach (all keys optional except summary and body on record):
+        {"summary": "...", "body": "...", "author": "...",
+         "commits": ["<git hash>"], "asset_versions": [{"vcs": "perforce", "external_id": "123"}],
+         "stakeholder_references": [{"system": "jira", "uri": "https://...", "title": "..."}],
+         "related_intent_ids": ["<intent_id>"]}
+    USAGE
+  end
+end