Bundle Keito agent skill with CLI

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.1.7] - 2026-06-16
+
+### Added
+
+- Bundle the `keito-time-track` agent skill with the CLI so `keito skill install` no longer depends on an external skill repository by default.
+- Add a gstack-style `./setup` entrypoint for source-checkout installs with Claude Code and Codex target selection.
+- Add `keito skill team-init optional|required` to write repo-level agent guidance and `.keito/config.example.yml`.
+- Add packaged lifecycle hook tests that exercise the bundled skill with a fake Keito CLI.
+- Add AI-native services positioning notes for agent billing, project attribution, and client profitability.
+
+### Changed
+
+- Keep the audit-first external skill install path available through `--source` and `--skip-skills-add`.
+- Document the bundled skill install, repo setup workflow, and release positioning in README and the agent guide.
+- Accept `calendar` and `desktop` as time entry source values alongside `web`, `cli`, `api`, and `agent`.
+
 ## [0.1.6] - 2026-05-12
 
 ### Changed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "keito-cli"
-version = "0.1.6"
+version = "0.1.7"
 edition = "2021"
 description = "CLI for AI agents and humans to track billable time against the Keito platform"
 license = "MIT"

README.md

@@ -4,6 +4,10 @@
 
 Track billable time against the [Keito](https://keito.ai) platform — from the terminal or from an AI agent.
 
+Keito is billing and profitability infrastructure for AI-native services teams:
+agent work is recorded against the same clients, projects, tasks, and invoices
+as human work, with metadata for margin and audit analysis.
+
 <p align="center">
   <img src="recordings/time-start-stop-optimised.gif" alt="keito demo" width="720" />
 </p>
@@ -91,14 +95,137 @@ Exit codes tell you exactly what happened — no need to parse error messages. S
 
 ## Agent Skill
 
-The Keito Agent Skill is installed from the GitHub skill repo, not from an npm package:
+The Keito Agent Skill ships with this CLI. It brings Keito to the places where
+agents already work by installing lifecycle hooks for Claude Code and OpenAI
+Codex CLI, then recording one `source=agent` time entry when a tracked coding
+session ends.
+
+### Requirements
+
+- Claude Code and/or Codex CLI
+- Git, Bash, and `jq`
+- Keito credentials via `keito auth login` or `KEITO_API_KEY` +
+  `KEITO_ACCOUNT_ID`
+- macOS/Linux: `./setup` can install the CLI through Homebrew or release
+  tarballs if `keito` is not already on `PATH`
+- Windows: install the binary from
+  [Releases](https://github.com/osodevops/keito-cli/releases) first, then run
+  the skill commands from Git Bash or WSL where `bash` and `jq` are available
+
+### Step 1: Install on your machine
+
+Open Claude Code or Codex and paste this. The agent can run the same
+source-checkout flow that gstack documents:
+
+```sh
+git clone --single-branch --depth 1 https://github.com/osodevops/keito-cli.git ~/.keito/keito-cli
+cd ~/.keito/keito-cli
+./setup
+```
+
+`./setup` installs the CLI if needed, installs the bundled `keito-time-track`
+skill, and configures hooks for Claude Code, Codex, or both. In an interactive
+terminal it asks which host to configure. In non-interactive runs it defaults
+to both.
+
+Target one host explicitly when needed:
+
+```sh
+~/.keito/keito-cli/setup --host claude
+~/.keito/keito-cli/setup --host codex
+~/.keito/keito-cli/setup --host both
+```
+
+If the CLI is already installed, this equivalent command uses the bundled skill
+without the source checkout:
 
 ```sh
-keito auth login
 keito skill install
 ```
 
-`keito skill install` uses `npx` only to run the open skills installer. The installer package is pinned to `skills@1.5.6` by default and can be overridden intentionally with `KEITO_SKILLS_PACKAGE`.
+Choose one target when needed:
+
+```sh
+keito skill install --agent claude-code
+keito skill install --agent codex
+```
+
+Check readiness:
+
+```sh
+keito skill doctor
+keito skill status --json
+```
+
+### Step 2: Configure each client repo
+
+From each client repository, invoke the skill once to map that worktree to a
+Keito client, project, and task:
+
+```text
+/track-time-keito
+```
+
+This writes `.keito/config.yml`, which is intentionally repo-local and should
+not be committed.
+
+### Team Mode
+
+For shared repos, use the same model as gstack team mode: the skill remains
+globally installed, and the repository commits only agent guidance plus an
+example config.
+
+From inside the shared repo:
+
+```sh
+~/.keito/keito-cli/setup --team optional
+git add AGENTS.md CLAUDE.md .gitignore .keito/config.example.yml
+git commit -m "add Keito tracking guidance for agent work"
+```
+
+Use `required` instead of `optional` when agents must stop before billable
+coding work until `/track-time-keito` has configured the repo:
+
+```sh
+~/.keito/keito-cli/setup --team required
+```
+
+If the CLI is already installed and the global skill is already configured, you
+can run only the repo bootstrap:
+
+```sh
+keito skill team-init optional
+keito skill team-init required
+```
+
+`team-init` writes `AGENTS.md`, `CLAUDE.md`, `.gitignore`, and
+`.keito/config.example.yml`. It does not vendor the skill into the repo. Do not
+commit `.keito/config.yml`; that file contains the local project/task mapping
+created by `/track-time-keito`.
+
+### How It Works
+
+- `./setup` is the gstack-style source-checkout installer. It keeps a stable
+  checkout at `~/.keito/keito-cli`, installs the CLI if needed, then calls
+  `keito skill install --source bundled`.
+- `keito skill install` materializes the bundled `keito-time-track` skill and
+  copies it into agent home directories:
+  `~/.claude/skills/keito-time-track` for Claude Code and
+  `~/.codex/skills/keito-time-track` for Codex.
+- The hook installers merge lifecycle hooks into `~/.claude/settings.json` and
+  `~/.codex/hooks.json` using `jq`.
+- `/track-time-keito` verifies auth, asks for the Keito client/project/task for
+  the current repo, and writes `.keito/config.yml`.
+- On agent session start, the hook records local session state. On session end,
+  the hook logs one Keito time entry with `source=agent` and metadata such as
+  repo path, branch, commit, and agent type.
+
+Audit-first external install remains available:
+
+```sh
+npx --yes skills@1.5.6 add osodevops/keito-skill -g -a codex -a claude-code -s keito-time-track -y --copy
+keito skill install --skip-skills-add
+```
 
 ## Features
 

docs/agent-guide.md

@@ -28,6 +28,47 @@ keito auth status --json
 
 Exit code `0` = ready. Exit code `1` = fix credentials.
 
+## Skill Installation
+
+Install the packaged Keito skill into Claude Code and Codex:
+
+```sh
+keito skill install
+```
+
+Install one host only when needed:
+
+```sh
+keito skill install --agent claude-code
+keito skill install --agent codex
+```
+
+For source-checkout installs, use the gstack-style setup entrypoint:
+
+```sh
+git clone --single-branch --depth 1 https://github.com/osodevops/keito-cli.git ~/.keito/keito-cli
+cd ~/.keito/keito-cli
+./setup
+```
+
+From each client repository, invoke the skill once:
+
+```text
+/track-time-keito
+```
+
+This writes `.keito/config.yml` with the selected Keito client, project, and
+task IDs. Do not commit that file. For shared repositories, run
+`keito skill team-init optional` or `keito skill team-init required` to add
+agent guidance plus `.keito/config.example.yml`.
+
+Check readiness:
+
+```sh
+keito skill doctor
+keito skill status --json
+```
+
 ## Discovery
 
 ### List Projects

docs/ai-native-services-positioning.md

@@ -0,0 +1,97 @@
+# Keito Positioning: AI-Native Services
+
+Keito should be positioned as billing and profitability infrastructure for
+AI-native services companies.
+
+## Why Now
+
+YC's Summer 2026 Request for Startups explicitly calls for **AI-Native Service
+Companies**: companies that do not sell software, but sell the completed
+service. YC also calls for **Software for Agents**, arguing that agents need
+machine-readable APIs, MCPs, CLIs, and documentation so they can use tools
+programmatically without a human in the loop.
+
+Sources:
+- https://www.ycombinator.com/rfs
+- https://github.com/garrytan/gstack
+
+The category implication is direct: if agents are doing client work, the
+software around services businesses has to become agent-native too. Billing,
+time tracking, project mapping, approvals, and profitability reporting cannot
+remain browser-only workflows for humans.
+
+## Category Frame
+
+Keito is not LLM cost observability.
+
+LLM observability answers:
+- Which model ran?
+- How many tokens did it use?
+- What did the inference cost?
+- Was latency or quality acceptable?
+
+Keito answers:
+- Which client and project did the agent work for?
+- What task was delivered?
+- What time or effort should flow into billing?
+- What did that work cost internally?
+- What margin did the client, project, workflow, or agent generate?
+
+Lightspeed's investment note on Paid frames the same gap as missing economic
+infrastructure for AI agents: traditional SaaS pricing breaks when agents are
+autonomous digital workers, and the missing capabilities are value proof,
+custom pricing, outcome and hybrid models, cost tracking, and customer
+profitability dashboards.
+
+Source:
+- https://lsvp.com/stories/the-ai-agent-economy-has-a-19-trillion-problem-our-investment-in-paid/
+
+## Buyer
+
+Primary buyer:
+- AI-native agencies and consultancies
+- Professional-services teams using coding, research, support, finance, or
+  operations agents
+- YC-style startups replacing outsourced services with agent-run delivery
+
+The buyer wants software-margin economics without losing service-business
+controls: client attribution, auditability, utilization, approval, invoices,
+and profitability.
+
+## Messaging
+
+Use this compact positioning:
+
+> Keito is the billing and profitability layer for AI-native services teams.
+> Agents log work against clients, projects, and tasks the same way humans do,
+> so firms can invoice accurately, prove value, and see margin by customer and
+> workflow.
+
+Supporting claims:
+- "Bring Keito to where agents work": ship a CLI plus Codex and Claude Code
+  skills, not a dashboard-only workflow.
+- "Track billable work, not just token spend": connect agent activity to
+  projects, invoices, and margin.
+- "One worktree, one client/project/task mapping": repo-local setup keeps
+  agent time from leaking across clients.
+- "Best-effort hooks, deterministic CLI": agent sessions should never fail
+  because billing telemetry failed, but failures must be logged and recoverable.
+
+## Product Implications For The CLI
+
+The CLI should prioritize:
+- Bundled agent skills for Codex and Claude Code.
+- A gstack-style install flow: install globally, then bootstrap each repo.
+- Deterministic `--json` commands and stable exit codes.
+- `source=agent` entries with metadata for session ID, agent type, skill, git
+  branch, git revision, duration, and draft status.
+- Repo-local `.keito/config.yml` selected by a wizard and excluded from git.
+- `keito skill status` and `keito skill doctor` for agent-readable readiness.
+
+MindStudio's monetization guide makes the margin reason explicit: successful
+AI-agent businesses need disciplined cost tracking and 60-75% gross margins;
+cost creep at the interaction level can erase margin. Keito should connect
+that cost discipline to the professional-services billing system.
+
+Source:
+- https://www.mindstudio.ai/blog/build-monetize-ai-agents-business