Docs: fix stale CLI references and broken links across READMEs

CLAUDE.md

@@ -7,8 +7,8 @@ This repo will evolve as we learn things. Expect experimentation.
 ## AAuth Specification
 
 The evolving AAuth specification lives in a separate repo:
-- Local path: `../../DickHardt/AAuth`
-- GitHub: https://github.com/DickHardt/AAuth
+- Local path: `../AAuth-spec`
+- GitHub: https://github.com/dickhardt/AAuth
 
 Key spec documents:
 - `README.md` — full specification overview

README.md

@@ -1,16 +1,19 @@
 # AAuth — Agent Auth for MCP
 
-TypeScript packages for adding [AAuth](https://github.com/DickHardt/AAuth) (Agent Auth) to MCP servers and agents.
+TypeScript packages for adding [AAuth](https://github.com/dickhardt/AAuth) (Agent Auth) to MCP servers and agents.
 
 AAuth is an agent-aware authentication protocol that lets AI agents prove their identity and obtain authorization using HTTP Message Signatures and JWTs.
 
 ## Packages
 
 | Package | Description |
 |---------|-------------|
+| [`@aauth/bootstrap`](./bootstrap) | CLI for setting up AAuth agent keys, person server registration, and hosting |
+| [`@aauth/fetch`](./fetch) | CLI for making AAuth-authenticated HTTP requests |
 | [`@aauth/mcp-agent`](./mcp-agent) | Agent-side AAuth: signed fetch, challenge-response, token exchange |
 | [`@aauth/mcp-server`](./mcp-server) | Server-side AAuth: token verification, challenge building, resource tokens |
-| [`@aauth/local-keys`](./local-keys) | Local dev key management via OS keychain |
+| [`@aauth/local-keys`](./local-keys) | Library for managing AAuth agent signing keys across hardware and software backends |
+| [`@aauth/hardware-keys`](./hardware-keys) | Native bindings for YubiKey PIV and macOS Secure Enclave |
 | [`@aauth/mcp-stdio`](./mcp-stdio) | stdio-to-HTTP proxy with AAuth signatures |
 | [`@aauth/mcp-openclaw`](./mcp-openclaw) | OpenClaw plugin for AAuth-authenticated MCP connections |
 
@@ -80,10 +83,12 @@ const token = await createResourceToken({ resource, authServer, agent, agentJkt
 ### Local development
 
 ```bash
-# Generate a key pair and store in OS keychain
-npx @aauth/local-keys https://yourusername.github.io
+# Generate keys, register with a person server, and publish them
+npx @aauth/bootstrap --ps https://hello.coop
 ```
 
+See [`@aauth/bootstrap`](./bootstrap) for the full setup flow.
+
 ## Protocol Support
 
 This implementation covers the core AAuth protocol flows. The following spec features are **not yet supported**:
@@ -93,7 +98,7 @@ This implementation covers the core AAuth protocol flows. The following spec fea
 
 ## Specification
 
-The AAuth protocol specification: [github.com/DickHardt/AAuth](https://github.com/DickHardt/AAuth)
+The AAuth protocol specification: [github.com/dickhardt/AAuth](https://github.com/dickhardt/AAuth)
 
 ## License
 

bootstrap/README.md

@@ -0,0 +1,92 @@
+# @aauth/bootstrap
+
+CLI for setting up AAuth agent keys, registering with a person server, and publishing keys to a hosting platform.
+
+Part of [aauth-dev/packages-js](https://github.com/aauth-dev/packages-js). Protocol spec: [dickhardt/AAuth](https://github.com/dickhardt/AAuth).
+
+## Quick Start
+
+```bash
+# Generate keys, register with a person server, and walk through hosting setup
+npx @aauth/bootstrap --ps https://hello.coop
+```
+
+The bootstrap flow detects available key backends (YubiKey PIV, macOS Secure Enclave, software), generates keys on the strongest available backend, registers your agent with a person server, and bundles agent skills that walk you through publishing keys on platforms like GitHub Pages, GitLab Pages, Cloudflare Pages, and Netlify.
+
+## Commands
+
+```
+npx @aauth/bootstrap <command> [options]
+
+Commands:
+  discover                 List available key backends (JSON)
+  generate [options]       Generate a key pair, output public JWK (JSON)
+  sign-token [options]     Sign an agent token with ephemeral cnf (JSON)
+  public-key [options]     Output public key(s) (JSON)
+  add-agent <url> [opts]   Register an agent URL in config
+  config                   Dump ~/.aauth/config.json
+  show                     Human-readable status overview
+  skill                    List available skills (JSON)
+  skill <name>             Show full skill instructions
+  help                     Show this help
+```
+
+### Generate options
+
+```
+--backend <name>         software (default), yubikey-piv, secure-enclave
+--algorithm <alg>        EdDSA (default for software), ES256, RS256
+--agent <url>            Associate key with an agent URL
+```
+
+### Sign-token options
+
+```
+--agent <url>            Agent URL (required)
+--agent-id <id>          Agent identifier (default: from config)
+--lifetime <seconds>     Token lifetime (default: 3600)
+```
+
+### Person server bootstrap
+
+Can be combined with any command:
+
+```
+--person-server <url>    Bootstrap with person server (alias: --ps)
+--local <name>           Local part of agent identifier (default: "local")
+--login-hint <hint>      Hint about who to authorize
+--domain-hint <domain>   Domain/org routing hint
+--provider-hint <name>   Upstream identity provider hint
+--tenant <id>            Tenant identifier
+```
+
+## For AI Agents
+
+If you are an AI agent helping a user set up AAuth, **do not guess what is available**. Run the CLI to detect the user's environment first:
+
+```bash
+# 1. Detect available hardware and software backends
+npx @aauth/bootstrap discover
+
+# 2. Check current state (existing agents, keys, hosting)
+npx @aauth/bootstrap show
+
+# 3. Load the setup skill for step-by-step instructions
+npx @aauth/bootstrap skill setup
+
+# 4. List available hosting platform skills
+npx @aauth/bootstrap skill
+```
+
+The `discover` output tells you what key backends are available on this machine. Use that — not assumptions — to guide key generation. Hardware backends (Secure Enclave, YubiKey) are always preferred over software (OS keychain).
+
+The `skill` commands return structured instructions for the setup flow and each hosting platform. Load and follow these rather than improvising.
+
+## Related Packages
+
+- [`@aauth/local-keys`](../local-keys) — underlying library for key management and signing (use this from other packages)
+- [`@aauth/fetch`](../fetch) — CLI for making AAuth-authenticated HTTP requests
+
+## License
+
+MIT

bootstrap/skills/platforms/cloudflare-pages.md

@@ -19,7 +19,7 @@ The user wants to publish their AAuth agent metadata and public keys via Cloudfl
 ## Prerequisites
 
 - `@aauth/local-keys` is installed
-- Keys have been generated (run `npx @aauth/local-keys show` to check)
+- Keys have been generated (run `npx @aauth/bootstrap show` to check)
 - Cloudflare account
 - `wrangler` CLI installed (`npm install -g wrangler`) and authenticated (`wrangler login`), OR a git repo connected to Cloudflare Pages
 
@@ -37,7 +37,7 @@ Ask the user which they plan to use.
 
 Run:
 ```
-npx @aauth/local-keys public-key
+npx @aauth/bootstrap public-key
 ```
 
 ### 2. Create or locate the project

bootstrap/skills/platforms/github-pages.md

@@ -20,7 +20,7 @@ The user wants to publish their AAuth agent metadata and public keys via GitHub
 ## Prerequisites
 
 - `@aauth/local-keys` is installed
-- Keys have been generated (run `npx @aauth/local-keys show` to check)
+- Keys have been generated (run `npx @aauth/bootstrap show` to check)
 - `gh` CLI is authenticated
 
 ## Steps
@@ -33,7 +33,7 @@ Ask the user for their GitHub Pages URL if not obvious. It will be `https://user
 
 Run:
 ```
-npx @aauth/local-keys public-key
+npx @aauth/bootstrap public-key
 ```
 
 This outputs all local public keys as JSON. Each key includes an `aauth` metadata object with `device` and `created` fields.

bootstrap/skills/platforms/gitlab-pages.md

@@ -20,7 +20,7 @@ The user wants to publish their AAuth agent metadata and public keys via GitLab
 ## Prerequisites
 
 - `@aauth/local-keys` is installed
-- Keys have been generated (run `npx @aauth/local-keys show` to check)
+- Keys have been generated (run `npx @aauth/bootstrap show` to check)
 - GitLab account
 - `glab` CLI installed and authenticated (`glab auth login`), OR `git` configured for GitLab
 
@@ -36,7 +36,7 @@ For the simplest setup, use the user Pages site: create a repo named `username.g
 
 Run:
 ```
-npx @aauth/local-keys public-key
+npx @aauth/bootstrap public-key
 ```
 
 ### 2. Locate or create the GitLab Pages repo

bootstrap/skills/platforms/netlify.md

@@ -19,7 +19,7 @@ The user wants to publish their AAuth agent metadata and public keys via Netlify
 ## Prerequisites
 
 - `@aauth/local-keys` is installed
-- Keys have been generated (run `npx @aauth/local-keys show` to check)
+- Keys have been generated (run `npx @aauth/bootstrap show` to check)
 - Netlify account
 
 ## Agent URL
@@ -36,7 +36,7 @@ Ask the user which they plan to use.
 
 Run:
 ```
-npx @aauth/local-keys public-key
+npx @aauth/bootstrap public-key
 ```
 
 ### 2. Create or locate the project

bootstrap/skills/setup.md

@@ -11,8 +11,8 @@ when: User wants to create an AAuth agent identity, generate keys, add a key fro
 Before giving the user ANY guidance, you MUST run these commands and use the output to determine what is available:
 
 ```
-npx @aauth/local-keys discover
-npx @aauth/local-keys show
+npx @aauth/bootstrap discover
+npx @aauth/bootstrap show
 ```
 
 Do NOT assume which backends are available. Do NOT suggest EdDSA or OS keychain keys unless `discover` shows no hardware backends. The discovery output is the source of truth for what this machine supports.
@@ -51,9 +51,9 @@ Do NOT pick a hosting platform or agent URL without asking the user.
 
 If the user already has an agent identity set up and wants to add a key from a new device (e.g. they got a new YubiKey, or they're on a new Mac with a Secure Enclave):
 
-1. Check existing setup: `npx @aauth/local-keys show`
-2. Discover backends: `npx @aauth/local-keys discover`
-3. Generate a key on the new hardware: `npx @aauth/local-keys generate --backend <backend> --agent <agent-url>`
+1. Check existing setup: `npx @aauth/bootstrap show`
+2. Discover backends: `npx @aauth/bootstrap discover`
+3. Generate a key on the new hardware: `npx @aauth/bootstrap generate --backend <backend> --agent <agent-url>`
 4. Add the new public key to the existing JWKS on the hosting platform (load the appropriate platform skill)
 5. The new key will be used automatically — key resolution matches any published key that has a local private key
 
@@ -63,7 +63,7 @@ If the user already has an agent identity set up and wants to add a key from a n
 
 Run:
 ```
-npx @aauth/local-keys discover
+npx @aauth/bootstrap discover
 ```
 
 This returns a JSON array of available backends with their supported algorithms. You MUST run this and use the output — do not skip this step.
@@ -73,8 +73,8 @@ This returns a JSON array of available backends with their supported algorithms.
 For each hardware backend in the discovery output, generate a key and associate it with the agent URL:
 
 ```
-npx @aauth/local-keys generate --backend yubikey-piv --agent <agent-url>
-npx @aauth/local-keys generate --backend secure-enclave --agent <agent-url>
+npx @aauth/bootstrap generate --backend yubikey-piv --agent <agent-url>
+npx @aauth/bootstrap generate --backend secure-enclave --agent <agent-url>
 ```
 
 Each command outputs JSON with:
@@ -83,19 +83,19 @@ Each command outputs JSON with:
 
 **Only generate a software key if no hardware backends are available:**
 ```
-npx @aauth/local-keys generate --agent <agent-url>
+npx @aauth/bootstrap generate --agent <agent-url>
 ```
 
 ### 3. Set the person server
 
 The person server URL is included as the `ps` claim in agent tokens. Set it during setup:
 ```
-npx @aauth/local-keys add-agent <agent-url> --person-server <person-server-url>
+npx @aauth/bootstrap add-agent <agent-url> --person-server <person-server-url>
 ```
 
 The default person server is `https://issuer.hello.coop`. If the user doesn't specify one, use the default:
 ```
-npx @aauth/local-keys add-agent <agent-url> --person-server https://issuer.hello.coop
+npx @aauth/bootstrap add-agent <agent-url> --person-server https://issuer.hello.coop
 ```
 
 ### 4. Choose a hosting platform
@@ -111,7 +111,7 @@ const platforms = listPlatforms()
 
 Or via CLI:
 ```
-npx @aauth/local-keys skill
+npx @aauth/bootstrap skill
 ```
 
 Platform skills are in `skills/platforms/`. Each platform's front matter includes discovery metadata:
@@ -148,22 +148,22 @@ Also mention that any static HTTPS hosting works — the platforms with skills j
 
 After the user chooses, register the hosting platform:
 ```
-npx @aauth/local-keys add-agent <agent-url> --hosting <platform> --repo <repo-identifier>
+npx @aauth/bootstrap add-agent <agent-url> --hosting <platform> --repo <repo-identifier>
 ```
 
 ### 5. Publish keys using the platform skill
 
 Load the full instructions for the chosen platform:
 ```
-npx @aauth/local-keys skill <platform-name>
+npx @aauth/bootstrap skill <platform-name>
 ```
 
 Follow the skill instructions to publish the keys.
 
 ### 6. Verify setup
 
 ```
-npx @aauth/local-keys show
+npx @aauth/bootstrap show
 ```
 
 This shows all configured agents, their keys, and which backends are available.