From abe9bf928053a0f481850e991deb01b74a9d5511 Mon Sep 17 00:00:00 2001 From: Ian Pascoe Date: Fri, 29 May 2026 10:57:14 -0400 Subject: [PATCH 1/9] refactor: replace `get_caplet` with `inspect` --- ...14Z__apps-landing-src-pages-index-astro.md | 108 ++ .oxfmtrc.json | 11 +- README.md | 25 +- apps/landing/package.json | 3 +- apps/landing/public/icon-header-dark.png | Bin 0 -> 2115 bytes apps/landing/public/icon-header-light.png | Bin 0 -> 2115 bytes apps/landing/src/pages/index.astro | 474 +++++---- apps/landing/src/styles/global.css | 831 ++++++++++------ apps/landing/test/campaign-copy.check.mjs | 69 ++ docs/benchmarks/coding-agent.md | 12 +- .../2026-05-29-caplets-growth-campaign.md | 233 +++++ ...2026-05-29-landing-proof-led-activation.md | 927 ++++++++++++++++++ ...-29-landing-proof-led-activation-design.md | 123 +++ package.json | 1 + packages/benchmarks/lib/surface.ts | 4 +- packages/core/src/capability-description.ts | 4 +- packages/core/src/cli.ts | 12 +- packages/core/src/cli/commands.ts | 6 +- packages/core/src/cli/completion.ts | 2 +- .../core/src/generated-tool-input-schema.ts | 4 +- packages/core/src/native/tools.ts | 2 +- packages/core/src/remote-control/dispatch.ts | 2 +- packages/core/src/remote-control/types.ts | 2 +- packages/core/src/result-content.ts | 2 +- packages/core/src/tools.ts | 8 +- packages/core/test/cli-completion.test.ts | 4 +- packages/core/test/cli-remote.test.ts | 12 +- packages/core/test/cli.test.ts | 8 +- packages/core/test/native-remote.test.ts | 2 +- packages/core/test/native.test.ts | 10 +- packages/core/test/registry.test.ts | 12 +- .../core/test/remote-control-dispatch.test.ts | 8 +- packages/core/test/tools.test.ts | 16 +- packages/opencode/test/opencode.test.ts | 10 +- packages/pi/test/pi.test.ts | 12 +- pnpm-lock.yaml | 41 +- 36 files changed, 2427 insertions(+), 573 deletions(-) create mode 100644 .impeccable/critique/2026-05-29T10-04-14Z__apps-landing-src-pages-index-astro.md create mode 100644 apps/landing/public/icon-header-dark.png create mode 100644 apps/landing/public/icon-header-light.png create mode 100644 apps/landing/test/campaign-copy.check.mjs create mode 100644 docs/plans/2026-05-29-caplets-growth-campaign.md create mode 100644 docs/plans/2026-05-29-landing-proof-led-activation.md create mode 100644 docs/specs/2026-05-29-landing-proof-led-activation-design.md diff --git a/.impeccable/critique/2026-05-29T10-04-14Z__apps-landing-src-pages-index-astro.md b/.impeccable/critique/2026-05-29T10-04-14Z__apps-landing-src-pages-index-astro.md new file mode 100644 index 0000000..db33a28 --- /dev/null +++ b/.impeccable/critique/2026-05-29T10-04-14Z__apps-landing-src-pages-index-astro.md @@ -0,0 +1,108 @@ +--- +target: apps/landing/src/pages/index.astro +total_score: 26 +p0_count: 0 +p1_count: 2 +timestamp: 2026-05-29T10-04-14Z +slug: apps-landing-src-pages-index-astro +--- + +#### Design Health Score + +| # | Heuristic | Score | Key Issue | +| --------- | --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Visibility of System Status | 3 | Copy buttons have feedback and tabs expose selected state, but there is no visible install success path or live state beyond copy feedback. | +| 2 | Match System / Real World | 3 | The core metaphor, capabilities instead of tool walls, is concrete for agent builders. Some labels still assume MCP fluency. | +| 3 | User Control and Freedom | 3 | Anchor navigation, copy fallback, and tab keyboard controls are solid. Hidden inactive panels create many invisible buttons in the DOM, but not user-visible traps. | +| 4 | Consistency and Standards | 3 | Visual system is cohesive, but numbered top nav and repeated eyebrow cadence conflict with the otherwise product-specific voice. | +| 5 | Error Prevention | 2 | Install commands are copyable, but there is no guardrail for prerequisites, failed installs, or what users should verify after `caplets serve`. | +| 6 | Recognition Rather Than Recall | 3 | The trace, proof panel, and install path make the model visible. Some advanced terms, `get_caplet`, `structuredContent`, and MCP client setup, rely on prior knowledge. | +| 7 | Flexibility and Efficiency of Use | 3 | Agent-specific tabs and copy buttons support fast use. The page does not yet expose a shortest path for experienced users above the fold. | +| 8 | Aesthetic and Minimalist Design | 2 | Strong editorial direction, but the page is long, card-heavy, and still carries AI-pattern residue: numbered nav, eyebrow chips, wide shadows, and many bordered containers. | +| 9 | Error Recovery | 2 | The product concept explains scoped error recovery, but the landing page does not help users recover from install or setup failure. | +| 10 | Help and Documentation | 2 | GitHub/config links exist, but contextual help is light and task-focused docs are not surfaced near the install commands. | +| **Total** | | **26/40** | **Acceptable: strong message, needs hierarchy and activation polish before broad launch.** | + +#### Anti-Patterns Verdict + +**LLM assessment**: This does not look like generic AI slop at first glance. The message is specific, the trace card is relevant, and the benchmark proof creates a sharper story than a normal SaaS landing page. The slop risk is structural rather than visual: too many sections use the same formula of small label, large heading, bordered container, and explanatory prose. The page says progressive disclosure, but the page itself asks visitors to process a long sequence of similarly weighted proof blocks. + +**Deterministic scan**: The CLI detector found 2 issues in `apps/landing/src/pages/index.astro`: + +- `em-dash-overuse`, warning, line 0: reported 5 `--` sequences. This is mostly a false positive from command-line flags like `--command` and frontmatter delimiters, not body copy. +- `numbered-section-markers`, advisory, line 0: top navigation uses `01`, `02`, `03`, which matches the numbered editorial scaffold ban. + +**Browser overlay / console evidence**: Injection succeeded on the live page at `http://127.0.0.1:4321/`. The detector console reported: uppercase body text, hero eyebrow chip, oversized H1, 1px border plus 100px shadow blur, wide tracking, long line length around 143 chars, and overused primary font. Several are advisory or noisy, but two align with the manual review: the eyebrow/numbered scaffold and the thin-border plus wide-shadow pattern. + +#### Overall Impression + +The landing page has a real argument: Caplets reduces tool-wall overload with progressive discovery. The best parts are the hero trace, the before/after comparison, and the deterministic benchmark proof. The biggest opportunity is to make the page behave like the product promise: one clear capability story first, then deeper evidence only as needed. Right now it still feels like every section is competing to prove the same point. + +#### What's Working + +1. **The core claim is memorable and specific.** “Capabilities, not giant tool walls” names the pain and the mechanism. It is much stronger than a vague agent-platform tagline. +2. **The trace card demonstrates the product instead of decorating it.** The hero’s `get_caplet → search_tools → get_tool → call_tool` flow helps technical readers understand the mental model quickly. +3. **The benchmark proof has launch value.** “106 flat tools became 3 capability cards” is concrete enough for Reddit, HN, and agent-builder audiences, provided the visual treatment stays sober. + +#### Priority Issues + +**[P1] The page contradicts its own progressive-disclosure premise** + +- **Why it matters**: The product says agents should not see every operation up front, but the landing page gives humans many similarly weighted sections, cards, proof blocks, tabs, trust details, and install steps. The message is right, but the experience still feels like a tool wall translated into marketing sections. +- **Fix**: Collapse the middle of the page into a tighter narrative: hero trace, benchmark proof, one trust strip, then install. Move secondary explanatory cards into expandable details or lower-priority documentation links. +- **Suggested command**: `$impeccable distill apps/landing/` + +**[P1] The activation path is too late and too similar in weight to the rest of the page** + +- **Why it matters**: Agent power users want the quickest route to proof. They should be able to install, add Context7, and recognize the aha moment without scrolling past multiple conceptual sections. +- **Fix**: Promote the Context7 aha path closer to the hero, or add a compact “Try it in 60 seconds” strip immediately after the hero/proof pair. Keep the final install card, but make it the expanded version, not the first activation cue. +- **Suggested command**: `$impeccable onboard apps/landing/` + +**[P2] AI-pattern residue weakens an otherwise specific brand** + +- **Why it matters**: The audience is agent power users and MCP server builders, exactly the people most sensitive to AI-generated landing-page tropes. Numbered nav markers, repeated eyebrow labels, wide tracking, and bordered card repetition make the page feel more templated than the product deserves. +- **Fix**: Remove `01/02/03` from nav, reduce eyebrow frequency, replace at least one card grid with a more native artifact, such as a config diff, terminal transcript, or source manifest. +- **Suggested command**: `$impeccable quieter apps/landing/` + +**[P2] Setup confidence is incomplete** + +- **Why it matters**: The page gets users to `caplets serve`, but does not answer “what should I see next?” or “what if it fails?” That creates a trust gap at the exact moment activation should peak. +- **Fix**: Add expected output and verification after the commands: one capability appears, then `get_caplet`, then scoped discovery. Add one concise troubleshooting line for Node version, missing `npx`, or MCP client connection. +- **Suggested command**: `$impeccable harden apps/landing/` + +**[P3] The hero visual treatment still has a heavy SaaS-card smell** + +- **Why it matters**: The trace card is conceptually good, but the 1px border plus broad soft shadow pattern is a known AI/devtool visual tell. It makes the strongest artifact feel more generic than it needs to. +- **Fix**: Either commit to a flatter technical artifact, like a real terminal/config panel with minimal shadow, or make it feel like a source manifest with sharper borders and less blur. +- **Suggested command**: `$impeccable polish apps/landing/` + +#### Persona Red Flags + +**Jordan, first-time agent-tool user** + +- Primary action: understand what Caplets does, then try it. +- Red flags: `MCP`, `structuredContent`, `get_caplet`, `search_tools`, and `call_tool` appear before enough plain-language anchoring for a new user. Jordan understands the headline but may not know whether Caplets is a CLI, MCP server, plugin, or framework until later. + +**Riley, deliberate stress tester** + +- Primary action: verify the claims before installing. +- Red flags: the benchmark claim is strong, but the page does not directly link from the proof asset to the deterministic benchmark report. Riley will want the source of “106 flat tools” and the exact test conditions. + +**Casey, distracted mobile user** + +- Primary action: scan on a phone, save or try later. +- Red flags: mobile has no horizontal overflow, which is good, but the hero alone is very tall and the full page is long. Casey reaches the install section only after several large sections. The top nav is available, but the primary “try it” cue is not persistent or early enough. + +#### Minor Observations + +- Touch targets are generally good, with most links and buttons at or above 44px. +- The hidden copy buttons in inactive tab panels show as 0×0 in measurement because panels are hidden. That is acceptable if screen reader exposure is also hidden by the `hidden` attribute. +- The repeated section-note/kicker pattern is useful in moderation, but the page uses it often enough to become a rhythm rather than a decision. +- The installed command now uses `context7`, which matches the activation story better than the older `docs` alias. +- The body background and warm tokens are established identity in this repo, but they still sit close to the current AI “paper” default. The dark integrations section helps break that pattern. + +#### Questions to Consider + +- What if the page had only one deep technical artifact above the fold, then let proof and install orbit around it? +- What would change if “try Context7 in 60 seconds” were the second thing users saw? +- Which details belong on the landing page, and which belong in docs for users already convinced? diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 64d8512..2f61360 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -1,4 +1,13 @@ { "$schema": "./node_modules/oxfmt/configuration_schema.json", - "ignorePatterns": [".brv/"] + "ignorePatterns": [".brv/"], + "plugins": ["prettier-plugin-astro"], + "overrides": [ + { + "files": ["*.astro"], + "options": { + "parser": "astro" + } + } + ] } diff --git a/README.md b/README.md index f4455f2..29344f9 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

Caplets

- Give agents capabilities, not tool walls.
+ Give your agent capabilities, not tools.
Turn MCP servers, APIs, and commands into focused agent capabilities.

@@ -28,10 +28,23 @@ Caplets turns MCP servers, APIs, and commands into focused agent capabilities: one card first, searchable tools next, inspectable schemas before calls, and preserved results after. -Caplets wraps each tool source as a capability an agent can discover, inspect, call, and recover from one step at a time. Instead of exposing a flat wall of operations, Caplets shows a compact capability card with source, status, and next actions. The agent chooses a domain first, then uses scoped operations like `search_tools`, `get_tool`, and `call_tool` only when it needs more detail. +Stop dumping every operation into context up front. Caplets wraps each tool source as a capability an agent can discover, inspect, call, and recover from one step at a time. Instead of exposing a giant flat wall of operations, Caplets shows a compact capability card with source, status, and next actions. The agent chooses a domain first, then uses scoped operations like `search_tools`, `get_tool`, and `call_tool` only when it needs more detail. For MCP-backed Caplets, the scoped operation set also includes resource discovery and reading, prompt listing and rendering, resource-template discovery, and completion for prompt or template arguments. Non-MCP backends expose focused tool and action operations. +## Try the aha moment + +Install Caplets, add Context7, and watch your agent see one capability before it searches downstream tools. + +```sh +npm install -g caplets +caplets init +caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp +caplets serve +``` + +In the deterministic benchmark, 106 flat tools became 3 top-level capabilities with an 87.8% smaller initial payload. Your agent starts with `context7`, then drills in through `inspect`, `search_tools`, `get_tool`, and `call_tool` only when needed. + ## Quick Start Caplets requires Node.js 22 or newer. @@ -73,7 +86,7 @@ caplets install spiritledsoftware/caplets github linear context7 Configured Caplets can be invoked directly from the CLI for agent-friendly scripts and smoke tests: ```sh -caplets get-caplet context7 +caplets inspect context7 caplets list-tools context7 caplets get-tool context7 resolve-library-id caplets call-tool context7 resolve-library-id --args '{"libraryName":"react"}' @@ -871,7 +884,7 @@ an existing destination file. ### Caplet Sets Use `capletSets` to expose another Caplets collection as nested Caplets. Each child Caplet appears -as one downstream tool and supports the full Caplets operation set: `get_caplet`, `check_backend`, +as one downstream tool and supports the full Caplets operation set: `inspect`, `check_backend`, `list_tools`, `search_tools`, `get_tool`, and `call_tool`. ```json @@ -1076,7 +1089,7 @@ Call one exact downstream tool: Available operations: -- `get_caplet`: return the configured capability card without starting the downstream server. +- `inspect`: return the configured capability card without starting the downstream server. - `check_backend`: verify the selected backend, whether MCP, OpenAPI, GraphQL, HTTP, CLI, or nested Caplets. - `list_tools`: return compact downstream tool metadata. - `search_tools`: search downstream tool names and descriptions within this Caplet. @@ -1086,7 +1099,7 @@ Available operations: Requests are strict: operation-specific extra fields are rejected, and `call_tool` requires `arguments` to be a JSON object. -Discovery operations (`get_caplet`, `check_backend`, `list_tools`, `search_tools`, and +Discovery operations (`inspect`, `check_backend`, `list_tools`, `search_tools`, and `get_tool`) return wrapper-generated results whose `structuredContent.caplets` field identifies the Caplet with `id`, plus backend, operation, status, and elapsed time when available. Discovery result objects and compact tool entries also use `id` for the diff --git a/apps/landing/package.json b/apps/landing/package.json index 174619b..2bac629 100644 --- a/apps/landing/package.json +++ b/apps/landing/package.json @@ -8,7 +8,8 @@ "build": "astro build", "dev": "astro dev", "preview": "astro preview", - "typecheck": "astro check" + "typecheck": "astro check", + "campaign:check": "node test/campaign-copy.check.mjs" }, "dependencies": { "@astrojs/check": "^0.9.9", diff --git a/apps/landing/public/icon-header-dark.png b/apps/landing/public/icon-header-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..7f54aa666a340b32a706753201b2fe6788b7aa18 GIT binary patch literal 2115 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