@foldspace_npm/harness 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,7 @@
 # @foldspace_npm/harness
 
-Build, inject and verify Foldspace agent experiences against a live app.
+Build the portable `dist/index.js` action artifact and verify it against a live
+app.
 
 **This package is the part that is the same in both architectures.** Everything
 else about how a builder runs differs between them; this does not.
@@ -13,7 +14,7 @@ else about how a builder runs differs between them; this does not.
 |---|---|---|
 | Who runs the agent | Claude Code on the builder's desktop | Claude Agent SDK in GCP |
 | Whose browser | an isolated Chrome the harness launches | the user's **own** Chrome |
-| How code reaches the page | CDP injection | Web Store extension injects a `<script src>` from the CDN |
+| How code reaches the page | harness CDP preparation | builder extension loads the cloud artifact |
 | Prerequisites | Claude Code, a client repo, Node, an isolated Chrome profile | the extension installed |
 | Session and cookies | in a profile the harness creates | the user's own, untouched |
 | Code and history | a git repo on the builder's machine | a workspace in the hosted environment |
@@ -50,13 +51,36 @@ exact failure this package was created to end. And the verb interface only stays
 honest while both implementations sit behind it; separate them and "the same
 action runs in both modes" quietly stops being true.
 
-A hosted container installs this and never calls `inject`. That is kilobytes of
-dead weight, against a contract that cannot drift.
+A hosted environment uses the same action source and build contract, but local
+`inject` and `attach` remain CDP-only commands. The harness does not generate a
+customer application extension.
 
 ---
 
 ## Use
 
+### Discover the CLI
+
+Human-readable help is grouped by workflow:
+
+```bash
+foldspace help
+foldspace help attach
+```
+
+Coding agents can inspect the same versioned command and capability contract:
+
+```bash
+foldspace help --json
+foldspace help attach --json
+```
+
+The installed `harness` binary is an alias for `foldspace`.
+
+The JSON describes current options, prerequisites, side effects, risks,
+capabilities, and next steps. It does not claim that future hosted-environment
+capability enforcement is already implemented.
+
 ### Create a project
 
 Create a configured actions project from the template bundled with the installed
@@ -71,7 +95,7 @@ Non-interactive / CI form:
 ```bash
 npx --yes @foldspace_npm/harness init my-agent \
   --product-id FR8JUQZAQRZB \
-  --agent-api-name my-agent \
+  --agent-key my-agent \
   --domain app.example.com \
   --name "My Agent"
 ```
@@ -81,12 +105,14 @@ When running directly from a harness checkout during development:
 ```bash
 node bin/cli.mjs init ../my-agent \
   --product-id FR8JUQZAQRZB \
-  --agent-api-name my-agent \
+  --agent-key my-agent \
   --domain app.example.com
 ```
 
-`--name` is optional and defaults to the target directory name. The product ID
-must be the bare ID, not an `EU-…` SDK key. The domain may be a hostname or an
+The Agent Key is the value shown in Agent Studio, such as `my-agent`.
+`--agent-api-name` remains a deprecated alias for `--agent-key`. `--name` is
+optional and defaults to the target directory name. The product ID must be the
+bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname or an
 HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
@@ -104,6 +130,35 @@ npm run attach
 The generated npm scripts intentionally remain the normal project interface;
 `foldspace init` is the one-time project creation command.
 
+### Choose an attach mode
+
+- **Swap (default):** the page already uses the configured product and agent.
+- **Bootstrap (`--bootstrap`):** the page has no Foldspace SDK.
+- **Replace (`--replace`):** the page embeds a different product or agent, or
+  has an SDK without the configured agent.
+
+Use `foldspace help attach` for mode requirements, effects, and safety options.
+
+### Verify actions through the agent
+
+`foldspace attach` does not invoke action handlers directly. It loads the local
+artifact, verifies that its action names exactly match the configured SDK agent,
+and then observes action callbacks while you exercise the normal agent
+experience.
+
+Action output identifies SDK callbacks and local `execute`/`render` phases:
+
+```text
+[actions] sdk:action show_account_360 executed
+[actions] local-handler:execute show_account_360 succeeded 412ms
+[actions] local-handler:render show_account_360 succeeded 18ms
+```
+
+Only action names, parameter keys, statuses, and durations are recorded; handler
+parameter values, results, and error messages are not. On detach, repeated page
+failures and bounded action observations are summarized. The observer and
+diagnostics are injected by the harness, so `dist/index.js` is not rewritten.
+
 ### Add the harness to an existing project
 
 ```bash
@@ -120,18 +175,14 @@ npm i -D @foldspace_npm/harness
 } }
 ```
 
-| Command | A | B |
-|---|:--:|:--:|
-| `foldspace init` | ✅ | ✅ |
-| `foldspace build` | ✅ | ✅ |
-| `foldspace deploy` | ✅ | ✅ — it *is* the delivery mechanism |
-| `foldspace inject` | ✅ | — no browser to launch |
-| `foldspace attach` | ✅ | replaced by the extension bridge |
-
 Every command resolves the **consuming** repo — `process.cwd()`, or
 `FOLDSPACE_PROJECT_DIR` so a hosted builder can point it at a workspace it
 controls. Config comes from the consumer's `foldspace.dev.json`.
 
+`foldspace deploy` is an explicit remote publication step that reads product
+and agent identity from the selected target in `foldspace.dev.json`. It requires
+local cloud credentials and is separate from local verification.
+
 ---
 
 ## Why this package exists at all