shaka 0.1.0.pre.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5c6e93c8ca7f20820fc1372d2f980e02f3555d99071197212fbf15453fb09ea
+  data.tar.gz: 27f43e62af62e855322b757c39c61dd4d7247fd232a2460778a17233b6e1b15f
+SHA512:
+  metadata.gz: 68927d2edef47eb9e97ffaa22ba71302792c8142efbdc74a3ce1894079dea1e9446fe529fc6d89df51bd24e0c79d2cac3022b2bf014dc87d7cddc8dbdc96805e
+  data.tar.gz: 1b11c42ce1eaa44cd3dccd6656505aaa85b14617435296e936bffbcd886b268b516f84c9b0953e7afdc846959e76d116c63ef8078863ab6323c5433b9a7c1723

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ShakaCode
+
+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,63 @@
+# Shaka
+
+Give your agent a task. Get a verified PR and a clear explanation.
+
+```text
+$shaka Fix the failing search test
+```
+
+You steer the work. Shaka takes it through delivery:
+
+- Reads your repository's instructions and asks about missing requirements.
+- Tests the behavior before fixing it, then runs your repository's checks.
+- Opens a pull request with a walkthrough of what changed and why.
+- Handles review findings and verifies the fixes.
+- Asks you to approve the merge, or merges when authorized and ready.
+
+## You choose who can merge
+
+**Ask:** the agent prepares the PR, then waits for your merge approval.
+**Auto:** you authorize the agent to merge once the verified revision passes required
+checks and approvals. Risky changes still need a human decision.
+Existing authority is reused; a review-only or PR-only request keeps that stopping point.
+
+## For people
+
+[Install Shaka and complete your first task →](docs/getting-started.md)
+
+| I want to… | Read |
+| --- | --- |
+| Choose merge authority, answer questions, or split a larger task | [Working with your agent](docs/working-with-your-agent.md) |
+| Use master and repository control towers to organize Shaka tasks | [Control towers](docs/control-towers.md) |
+| Understand review findings or a blocked PR | [Review handling](docs/review.md) |
+| Evaluate code, UI, or documentation changes | [Verification and reader trials](docs/verification.md) |
+| Understand model, effort, and token reports | [Usage reporting](docs/usage-reporting.md) |
+| Check supported hosts and their limits | [Host support](docs/host-support.md) |
+| Upgrade or remove an installation | [Installation maintenance](docs/getting-started.md#upgrade) |
+
+### For open-source maintainers and contributors
+
+Open-source work starts with validating issues, PRs, and their comments before
+acting on them. Treat material from strangers as untrusted input. Verify who supplied
+it, whether they are authorized for the action, and whether the claim or change is valid.
+Recognized team members and repository-approved bots should fit the ordinary workflow;
+recognition alone does not make their content correct or grant permission to execute code.
+
+See [open-source intake and current limits](docs/working-with-your-agent.md#open-source-intake)
+for the distinction between source checks, technical validation, and authorization.
+The proposed public-comment filter in [PR #43](https://github.com/shakacode/shaka/pull/43)
+is only part of this work; complete bot/team handling is not yet established.
+
+## For agents and contributors to Shaka
+
+Start with the [agent procedure](skills/shaka/SKILL.md). Each repository's `AGENTS.md`
+supplies its commands and authority; [Shaka's contributor instructions](AGENTS.md)
+name this project's setup and checks. See the [requirements](docs/pilot-plan.md)
+and [gem packaging guide](docs/packaging.md) for design and distribution.
+The procedure owns execution; linked guides explain decisions and evidence for
+people and agents. Keep shared rules in one place and follow the procedure's references.
+
+In Claude Code, send `/shaka`. Codex is the reference host; [Claude Code consumer delivery
+and Cursor are unverified](docs/host-support.md). Public pilot: [progress](https://github.com/shakacode/shaka/issues/1).
+
+[MIT licensed](LICENSE). Copyright © 2026 ShakaCode.

data/bin/install

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'optparse'
+
+skills_dir = nil
+parser = OptionParser.new do |options|
+  options.banner = 'Usage: bin/install --skills-dir DIR'
+  options.on('--skills-dir DIR', 'Explicit destination for the isolated skill') { |value| skills_dir = value }
+  options.on('-h', '--help', 'Show this help') do
+    puts options
+    exit
+  end
+end
+
+begin
+  parser.parse!
+  raise OptionParser::MissingArgument, '--skills-dir DIR' if skills_dir.nil?
+  raise OptionParser::InvalidArgument, 'DIR must not be empty' if skills_dir.strip.empty?
+  raise OptionParser::InvalidArgument, ARGV.join(' ') unless ARGV.empty?
+
+  links = %w[shaka].map do |name|
+    [File.realpath("../skills/#{name}", __dir__), File.join(File.expand_path(skills_dir), name)]
+  end
+  conflict = links.find do |source, destination|
+    (File.exist?(destination) || File.symlink?(destination)) &&
+      !(File.symlink?(destination) && File.readlink(destination) == source)
+  end
+  abort "Refusing existing destination: #{conflict.last}" if conflict
+
+  links.each do |source, destination|
+    if File.symlink?(destination)
+      puts "Already installed: #{destination}"
+    else
+      FileUtils.mkdir_p(File.dirname(destination))
+      File.symlink(source, destination)
+      puts "Installed: #{destination} -> #{source}"
+    end
+  end
+rescue OptionParser::ParseError, SystemCallError => e
+  warn e.message
+  exit 1
+end

data/docs/control-towers.md

@@ -0,0 +1,128 @@
+# Use control towers with Shaka
+
+A **Master Control Tower (MCT)** keeps priorities and dependencies clear across
+repositories. A **Repository Control Tower (RCT)** keeps one repository's work
+moving. Each implementation or PR repair has one owner who uses the installed
+`$shaka` skill through the requested outcome.
+
+These are optional roles in your existing tasks. They need no new service,
+workflow database, scheduler, or Shaka extension. Start with one repository and
+one real delivery. Keep using Shaka directly when a tower would add no value.
+
+## Who owns what
+
+| Role | Owns | Completion evidence |
+| --- | --- | --- |
+| Master tower | Cross-repository priorities, dependencies, and consequential decisions | The requested outcomes and remaining dependencies, linked to repository results |
+| Repository tower | Task selection, existing-owner reconciliation, sequencing, and follow-through | Each selected task has one accountable delivery owner and a verified result or blocker |
+| Shaka delivery owner | Intake, implementation, checks, review, walkthrough, and authorized merge or handoff | The PR's current revision, validation, independent review when required, and actual final state |
+
+The RCT can be the delivery owner for one bounded task. If a separate task
+already owns the work, continue there; the RCT follows its result instead of
+also editing or merging its PR. Transfer ownership explicitly before taking over.
+An idle icon, an old comment, or a title is not proof that work is abandoned.
+
+Keep requirements in their original issue or tracker and delivery evidence on
+GitHub. A private portfolio page may link to them; do not copy private priorities,
+task links, or customer context into a public PR. A dashboard is a view, not
+proof of ownership, authorization, or completion.
+
+## Start with existing tasks
+
+Give an existing portfolio task this role and a bounded outcome:
+
+```text
+Act as the Master Control Tower for the repositories and outcome I name.
+Keep priorities, cross-repository dependencies, and decisions clear. Reuse
+existing repository towers and delivery owners. Route each implementation or
+PR repair through the installed $shaka skill in the verified target checkout.
+Keep one delivery owner per task. Follow verified PR outcomes; do not become
+a second writer or merge executor for an owned PR. Preserve existing authority,
+pauses, work limits, and private context. Report material results and the next
+decision or blocker. This role does not authorize new tasks or scheduled work.
+```
+
+Give the repository's existing task this role and its selected work:
+
+```text
+Act as the Repository Control Tower for the repository I name. Read its trusted
+AGENTS.md and reconcile the selected issue or PR with live GitHub state and
+existing task ownership. Finish useful existing work before admitting more.
+For each delivery, use the installed $shaka skill. Either own that bounded task
+here or continue through its existing owner; do not split closeout responsibility.
+Preserve the repository's commands, review requirements, and merge authority.
+Use isolated worktrees for independent writers and never duplicate a target.
+Keep real decisions visible and verify the final PR state before reporting done.
+Preserve explicit pauses and limits; do not create background work from this role.
+```
+
+Then supply an actual assignment, replacing the brackets with verified facts:
+
+```text
+$shaka Complete [issue/PR URL or task description] in [owner/repository].
+Checkout: [verified local path]. Success means [observable result].
+Existing owner: [task reference, or confirmed unowned].
+Merge authority: [existing decision and scope, or ask if unset].
+Dependencies and limits: [known prerequisites, pauses, and stopping point].
+```
+
+The installed Shaka procedure owns model selection, intake, verification, review,
+and merge handling. Reuse answers already given for the same task. A tower prompt
+does not change the host's model, replace the installed skill, or authorize
+delegation. Use supported host controls and the user's actual authorization.
+
+## Keep decisions and waits accurate
+
+Use Shaka's **ask** and **auto** preferences. Preserve an existing decision's
+repository, task, revision, and risk scope; do not convert an old workflow's
+setting into broader Shaka authority. Unknown authority defaults to asking.
+Record the preference early; in Ask, prepare the reviewable result before seeking
+the actual merge decision. Reuse authority already granted for that scope.
+
+CI waits, missing reviews, and repairable conflicts remain with the delivery
+owner. Finish independent work while waiting. Send a decision to the human only
+when their input is needed, with the exact question, recommendation, PR evidence,
+and owning task. If an attention desk already exists, reuse its established
+writer and response channel; Shaka does not require or implement a desk.
+An answered question is no longer unanswered, but the owner must still verify
+the requested action completed. A queued message proves neither consumption
+nor completion.
+
+An Auto preference cannot compensate for missing protection or checks. The
+[merge boundary](pilot-plan.md#merge-boundary) requires observable native checks
+enforced for the acting account. If GitHub cannot expose that protection, retain
+the prepared PR and report the limitation; do not switch submission paths to
+evade the guard. A tower does not grant deployment or other consequential authority.
+
+## Adopt and prove the path
+
+Choose an active repository where the user wants a result. Adopting Shaka does
+not require changing, validating, or merging the workflow it replaces. Treat
+retired workflow repositories as reference material unless the user explicitly
+assigns work there. Their PRs and checks are not adoption dependencies.
+
+1. Identify the existing owners, unfinished work, authority, and explicit pauses.
+   Verify the target checkout and installed Shaka source outside that checkout.
+2. Review and select a published revision of the role instructions. A paused
+   tower needs explicit authorization to resume its named work. Adoption alone
+   does not release other pauses, renew limits, or restart scheduled tasks.
+3. Apply the role to one existing RCT and complete one real Shaka task. Require
+   the correct repository, no duplicate owner, actual checks, current review when
+   required, a commit-bound walkthrough, and the authorized merge or PR handoff.
+4. Read back GitHub's final state and have the master consume the result. Record
+   the tested source revision and outcome once in the existing rollout record.
+   Delivery, acknowledgment, and verified completion are different facts.
+5. Expand to the remaining repositories only after that pilot succeeds and their
+   adoption is authorized. Reuse their commands, owners, and approval requirements.
+
+Check negative cases too: an owned target must reuse or wait for its owner;
+an Ask task must wait for its merge decision; a changed head needs fresh evidence;
+a paused task must remain paused without a release decision; a retired repository
+must not receive new work from adopting Shaka. Apply a user's scope correction
+before continuing an earlier assignment. Record observed actions, not just a
+reader's promise to follow the prompt. A document review or passing unit suite
+alone does not establish tower adoption.
+
+To roll back, stop new admissions under the changed role, preserve unfinished
+owners and PRs, and restore the previous reviewed instructions. Do not remove
+other workflows or discard their active work as part of adopting Shaka.

data/docs/getting-started.md

@@ -0,0 +1,138 @@
+# Install and complete your first task
+
+Shaka guides an agent from a task description to a tested, reviewed GitHub PR.
+Start with a small change in a repository you trust, such as fixing a search test
+or correcting a broken link in a documentation site.
+
+## Prerequisites
+
+You need Git, Ruby 3.4, authenticated [GitHub CLI](https://cli.github.com/),
+and a signed-in Codex app, [Codex CLI](https://learn.chatgpt.com/docs/codex/cli#getting-started),
+or [Claude Code](https://code.claude.com/docs/en/setup).
+Check `git --version`, `ruby --version`, and `gh auth status` in your terminal;
+run `gh auth login` if needed. Codex terminal users also need `codex --version` to work;
+Claude Code users need `claude --version`.
+The skill uses no development gems. Keep your application's own Ruby version.
+
+Your repository's `AGENTS.md` should name setup, validation, and review commands,
+the base branch, and who may authorize merging. Shaka reads the scripts and offers
+a small addition if required instructions are missing. Existing instructions count.
+To merge, GitHub must enforce required checks for the acting account, allow squash
+merges, and satisfy required approvals. Otherwise, Shaka explains the blocker on the PR.
+
+## Install in the Codex app
+
+Keep this trusted source checkout outside the repositories you will edit.
+If it already exists, follow **Upgrade** below. First, get the source:
+
+```bash
+mkdir -p "$HOME/agent-tools"
+git clone https://github.com/shakacode/shaka.git "$HOME/agent-tools/shaka"
+```
+
+Inspect the cloned `bin/install` and `skills/shaka/` source. Then, with Ruby 3.4
+available, install the skill:
+
+```bash
+"$HOME/agent-tools/shaka/bin/install" --skills-dir "$HOME/.agents/skills"
+```
+
+<a id="use-shaka-in-the-codex-app"></a>
+
+Open a Codex task in the repository you want to change. The skill should appear on
+the next turn; restart Codex if it does not. Installation preserves other skills
+and settings. The task uses the app's existing permissions; this installation does
+not create a sandbox for untrusted contributor code.
+
+<a id="use-shaka-in-claude-code"></a>
+
+## Install in Claude Code
+
+After cloning the source as above, install into Claude Code's user skills directory:
+
+```bash
+"$HOME/agent-tools/shaka/bin/install" --skills-dir "$HOME/.claude/skills"
+```
+
+Start Claude Code in the repository you want to change, and use `/shaka` wherever
+this guide shows `$shaka`. Claude Code runs your personal skill instead of a
+same-named skill in a repository's `.claude/skills`, and the skill stops if it was
+loaded from inside the checkout. Keep the trusted source outside any `--add-dir`
+directory. Your usual permission mode applies; installation adds no sandbox.
+
+## Complete your first task
+
+Send this, replacing the example with your issue number, task URL, or description:
+
+```text
+$shaka Fix the failing search test. Bring the finished PR back for my approval.
+```
+
+An issue number uses the current repository. A URL can identify another one;
+Shaka asks for its checkout if needed. If it cannot read the task, paste the
+requirements. Private task content stays out of public PRs unless you allow sharing.
+
+The agent reads the task and recommends a model and effort. It pauses for **ready**
+unless you explicitly supplied matching model and effort and clearly authorized an
+immediate start, with those settings active in the host. Unavailable or conflicting
+settings still require one user action. It implements on a branch, runs your repo's
+checks, opens a PR with a walkthrough, and handles review findings. You get the PR
+link, validation result, and any blocker; detailed evidence is on the PR.
+
+The example chooses **Ask**: you make the merge decision after the PR is ready.
+To choose **Auto**, say “Merge when checks and required approvals pass” instead.
+Existing merge authority is reused; review-only and PR-only requests stop there.
+Auto still waits for required approvals and raises risky decisions. If a task stops
+at a blocker, resume it to continue; it does not keep trying in the background.
+
+## Use a fresh terminal session
+
+After cloning the source, install into a dedicated directory outside your repositories:
+
+```bash
+"$HOME/agent-tools/shaka/bin/install" --skills-dir "$HOME/agent-tools/shaka-pilot/skills"
+export PATH="$HOME/agent-tools/shaka-pilot/skills/shaka/scripts:$PATH"
+shaka work --repo /path/to/your/repository "Fix the failing search test. Use Ask."
+```
+
+Replace the repository path. This starts interactive Codex with the same task flow.
+If your application's version manager selects another Ruby, run the command from
+outside that checkout with Ruby 3.4 selected. Add the `PATH` line to your shell
+startup file to make `shaka` available in new terminals.
+The launcher uses a separate temporary session and native approval prompts;
+[host support](host-support.md#startup-boundary-and-current-validation) records its tested limits.
+
+## Upgrade
+
+Set `shaka_source` to your existing trusted checkout. Inspect its remote and local
+changes first; it should point to `shakacode/shaka`. Preserve local edits and resolve
+conflicts before switching or pulling.
+
+```bash
+shaka_source="$HOME/agent-tools/shaka"
+git -C "$shaka_source" remote -v
+git -C "$shaka_source" status --short
+git -C "$shaka_source" switch main
+git -C "$shaka_source" pull --ff-only
+"$shaka_source/bin/install" --skills-dir "$HOME/.agents/skills"
+```
+
+Start a fresh task after upgrading. For a terminal install, pass your dedicated
+skills directory instead; for Claude Code, pass `$HOME/.claude/skills`. Earlier installs used `agent-workflows-v2` or
+`shakacode-workflows` source directories: keep that location and use it above.
+Inspect old `sw` and `aw` symlinks and unlink only those belonging to this installation.
+Replace any old `sw/scripts` shell `PATH` entry with the `shaka/scripts` path above.
+
+## Remove or roll back
+
+Inspect the link with `ls -l "$HOME/.agents/skills/shaka"`. If it points to your
+Shaka installation, remove it:
+
+```bash
+test -L "$HOME/.agents/skills/shaka" && unlink "$HOME/.agents/skills/shaka"
+```
+
+Use your dedicated skills directory for a terminal install and remove its shell
+`PATH` entry. For Claude Code, use `$HOME/.claude/skills`. Inspect and remove any old `sw` or `aw` links individually; preserve
+unrelated skills and real directories. To roll back, remove the verified links,
+check out the prior trusted source revision, and run that revision's installer.

data/docs/host-support.md

@@ -0,0 +1,117 @@
+# Host support
+
+Codex CLI is the reference host for this pilot and Claude Code the second host.
+Follow the [getting-started guide](getting-started.md) for installation and your
+first task. Neither Claude Code nor Cursor has a verified complete V2 consumer
+delivery yet.
+
+The hosts share one `shaka` skill and the same Ruby helpers for GitHub
+operations. Your repository keeps its existing `AGENTS.md`, commands, and policy.
+Host-specific work covers installation, instruction loading, execution permissions,
+and reading native usage records. It does not create three copies of the workflow.
+
+## What has been verified
+
+These observations were made on September 14 and 15, 2026. A successful install or CLI
+startup does not establish a complete workflow, and workflow success does not
+establish complete usage attribution.
+
+| Capability | Codex CLI 0.154.0 | Claude Code desktop 2.1.270, CLI 2.1.272 | Cursor CLI 2026.09.10-fd3934a |
+| --- | --- | --- | --- |
+| Installation and startup | Dedicated skill installation and explicit trusted-file startup checked. | A symlinked personal skill loaded in the desktop app and in `claude -p`; `/shaka` asked for the task and merge preference and stopped before edits. A same-named repository skill did not replace it. | Dedicated CLI package version/help checked; V2 instruction activation unverified. |
+| OS write boundary | A native workspace sandbox denied writes to the separate trusted source, installed link, and link directory while allowing the session and target checkout. | No launcher or sandbox; the user's permission mode applies. Not separately probed. | Native V2 sandbox boundary unverified. |
+| Real workflow | Protected PR operations exercised in V2. A fresh CLI task implemented and verified the Astro website guides using its repository instructions; the owning task handled publication. | Consumer delivery unverified. | Consumer delivery unverified. |
+| Usage | Reader matched 14 real CLI responses and repeated-source input without double counting; attribution remains partial. | Reader matched an independent per-response aggregate for a desktop session with a subagent and two models, and Claude Code's own totals for two CLI runs. | Complete V2 token and effort reporting unverified. |
+
+The Codex write test establishes that particular local boundary. It does not
+establish equivalent behavior in the desktop app, other versions, or other hosts.
+Repeated consumer use, including failed checks, changed PR heads, and Ask/Auto
+stopping behavior, is still required before claiming broader adoption.
+
+## Codex first
+
+Use the canonical [startup instructions](getting-started.md).
+Keep the trusted workflow source and installed link outside both the writable
+session directory and target checkout. The guided startup names the trusted skill for the agent; do not add a discovery
+link inside the writable session.
+
+The launcher or direct invocation must establish the intended permissions even
+when the user's existing configuration grants broader access. Temporary writable
+directories also count: placing the trusted skill in a system temporary directory
+can undermine an otherwise separate installation. See the
+[Codex permissions documentation](https://learn.chatgpt.com/docs/permissions)
+for the host's controls; the getting-started guide owns the tested V2 recipe.
+
+## Startup boundary and current validation
+
+Each launch creates a private temporary session outside the consumer checkout,
+reads the trusted skill by its absolute source path, and directs repository
+commands to the checkout. It adds no skill link to that writable session. The
+launcher rejects canonical or lexical overlaps between writable paths and the
+trusted source or installed command/link parents. If your `TMPDIR` is inside the
+target checkout, choose a temporary directory outside it before launching.
+
+The native shell sandbox permits writes in the session and target checkout,
+overrides extra writable roots, excludes ambient temporary directories, and uses
+approval prompts for this launch. It sets shell `TMPDIR` and zsh `TMPPREFIX`
+inside the session's temporary directory. It leaves authentication and model settings
+alone. Session scratch stays in the system temporary directory after Codex exits;
+the launcher leaves no background process. Codex still shows its native directory
+trust and command-approval prompts; the launcher does not bypass them.
+
+On Codex CLI 0.154.0, separate startup and native sandbox probes kept candidate
+skill metadata out of the initial prompt and denied writes to the trusted source,
+installed link, and link parent while permitting session and checkout writes.
+A live terminal trial verified temporary-file access, protected-file write denial,
+and automatic native usage discovery. A separate native sandbox check reproduced
+and corrected zsh heredoc failures using the session temp prefix. Launcher tests
+verify the executed arguments and path refusals. App startup,
+other host versions, and complete isolation remain unverified. The sandbox does
+not establish that dependencies are trustworthy or remove secrets from published
+text. Do not approve an escape merely to make a check pass.
+
+## Claude Code
+
+Use the [Claude Code install recipe](getting-started.md#use-shaka-in-claude-code).
+Claude Code runs a personal skill instead of a same-named skill in a repository's
+`.claude/skills`, as its [skill locations](https://code.claude.com/docs/en/skills)
+document; the September 15 trial confirmed this with a canary repository copy.
+There is no `shaka work` launcher for Claude Code. Start `claude` in the repository,
+keep the trusted source outside any `--add-dir` directory, and rely on the permission
+mode you already use. The next required evidence is a complete ordinary consumer PR
+delivered with `/shaka`.
+
+## Cursor
+
+Keep an existing, authenticated host configuration in place when preparing a
+compatibility trial. Check its version and available controls before starting.
+Native `SKILL.md` support is [documented for Cursor](https://cursor.com/docs/skills),
+but shared file format alone does not prove V2 activation or safe execution.
+
+Cursor user skills can be installed at `~/.cursor/skills` with the standard
+installer. A September 14 trial did not find the skill through `~/.agents/skills`,
+so use the Cursor-specific directory and still confirm discovery in a new Agent chat.
+The trial did not establish a complete Cursor workflow or a supported launch recipe.
+
+The checked Cursor CLI exposes `--workspace`, `--add-dir`, `--sandbox`, and
+`--plugin-dir`. Its public help has no direct skill-file option. The native sandbox
+and V2 delivery have not been exercised, so these flags are not sufficient grounds
+for a supported launch recipe.
+
+Inspect the targets in the [official Cursor installation instructions](https://cursor.com/docs/cli/installation)
+before installing. The inspected upstream installer creates both `agent` and
+`cursor-agent` commands; those names can collide with another installed tool.
+Prefer an existing signed-in host for a trial. The dedicated package startup check
+did not change global command links or establish a general installation method.
+
+## Usage is a separate capability
+
+Follow [usage reporting](usage-reporting.md) for the supported reader, available
+fields, and attribution limits. Record host/version separately from provider/model.
+Preserve native reasoning settings and cache categories; similarly named settings
+across hosts are not equivalent measurements.
+
+Report missing data as `UNKNOWN`, and label shared or partial coverage. Publish
+aggregate metadata only, without prompts, raw sessions, account details, or local
+paths. Missing usage does not block an otherwise authorized merge, and CLI startup
+does not establish model usage or savings.

data/docs/packaging.md

@@ -0,0 +1,60 @@
+# Build and test the pilot gem
+
+The gem packages the same skill, installer, and Ruby helpers as the source checkout.
+It adds no runtime gems and does not install a global agent profile. This is a local
+prerelease package; nothing has been published to RubyGems.org.
+
+Build from the trusted source directory; RubyGems reads package files relative
+to the working directory. With the source installation from the first-use guide:
+
+```bash
+cd "$HOME/agent-tools/shaka"
+gem build shaka.gemspec
+```
+
+To try the built package without changing your application bundle or normal gem
+installation, use a separate gem home. These environment values apply only to the
+individual commands:
+
+```bash
+shaka_gem_home=$(mktemp -d)
+GEM_HOME="$shaka_gem_home" GEM_PATH="$shaka_gem_home" gem install --local --no-document ./shaka-0.1.0.pre.1.gem
+GEM_HOME="$shaka_gem_home" GEM_PATH="$shaka_gem_home" "$shaka_gem_home/bin/shaka" --help
+```
+
+Keep this temporary home for packaging checks only. A real pilot installation must
+keep its trusted source outside the agent's writable directories, including any
+temporary directories the host allows. Do not export the test gem environment into
+your application's shell or add the pilot to its Gemfile.
+
+The package also contains `shaka-install --skills-dir DIR`, which calls
+the existing explicit-directory installer. Use it only when you want a link in a
+chosen skill directory. It preserves existing content and refuses to replace a
+different source. The [first-use guide](getting-started.md) explains the trusted
+source and host startup boundaries.
+
+## Upgrade, rollback, and removal
+
+RubyGems installs each version in its own directory. A manually installed skill
+link keeps pointing to its original version. To change that link, inspect its
+destination, remove only the known pilot symlinks, then run the new version's
+installer. Do not remove a foreign directory or silently repoint another skill.
+You can retain the prior gem version and relink it for rollback.
+
+Remove the pilot `shaka` skill link before uninstalling the version it points to. For the
+isolated packaging check above:
+
+```bash
+GEM_HOME="$shaka_gem_home" GEM_PATH="$shaka_gem_home" gem uninstall shaka --all --executables
+```
+
+A two-version artifact trial also confirmed explicit upgrade and rollback while
+preserving an existing skill link. The package test builds and installs the actual gem into a temporary home, runs
+the installed helper and installer from outside the source checkout, then removes
+the package. Existing installer tests cover repeat installation, collisions, and
+source updates. These checks validate the artifact; they do not establish host
+compatibility or authorize a registry release.
+
+The provisional package is `shaka` version `0.1.0.pre.1`, distributed under the
+[MIT license](../LICENSE). The gem includes the license and declares it in its metadata.
+Registry publication still requires separate approval. Packaging uses [standard RubyGems tooling](https://guides.rubygems.org/make-your-own-gem/).