docs: add AI guide and link Claude marketplace

Author: lambdalisue

AI.md

@@ -0,0 +1,85 @@
+# AI Scenario Testing Guide
+
+How to let AI assistants write and run Probitas scenario tests.
+
+## Setup for Claude Code (Recommended)
+
+Install the official marketplace and Probitas plugin:
+
+```bash
+/plugin marketplace add jsr-probitas/claude-plugins
+/plugin install probitas@jsr-probitas
+```
+
+Enable it in `.claude/settings.json`:
+
+```json
+{
+  "plugins": {
+    "marketplaces": ["jsr-probitas/claude-plugins"],
+    "installed": ["probitas@jsr-probitas"]
+  },
+  "enabledPlugins": {
+    "probitas@jsr-probitas": true
+  }
+}
+```
+
+## How to Ask the AI
+
+- Be explicit about the scenario goal, inputs, and expected outcomes.
+- Share API/DB schemas or example payloads; do not let the AI guess.
+- Provide env vars and endpoints (e.g., `API_URL`) up front.
+- Request tags and timeouts if needed (e.g., `tags: ["api", "slow"]`).
+- Ask for `ctx.previous` data flow when steps depend on each other.
+
+Example prompt snippet:
+
+> Write a Probitas scenario for POST /users that returns `{ id: number }`.
+> Use API_URL env, tag as `api`. Step 1: create user, return id. Step 2: GET
+> by id, expect 200 and name match. Use fluent expect chain.
+
+## Scenario Authoring Rules (What the AI must follow)
+
+- Use the `scenario-writer` agent for `*.probitas.ts`.
+- Keep steps in one scenario only when they depend on `ctx.previous`; otherwise
+  split into separate scenarios.
+- Always `export default` and finish builders with `.build()`.
+- Register clients with `.resource()` and use env-driven URLs:
+  `Deno.env.get("API_URL") ?? "http://localhost:8080"`.
+- Use fluent `expect()` chains—no manual `if/throw` checks.
+- `.setup()` should return a cleanup function when it creates fixtures.
+- One responsibility per step; return data needed by subsequent steps.
+- Use tags for filtering and retries/timeouts where appropriate.
+
+## Running and Checking via AI
+
+Claude Code commands:
+
+- `/probitas-init` — initialize a project
+- `/probitas-new <type>` — scaffold scenario templates
+- `/probitas-check` — format, lint, and type-check scenarios
+- `/probitas-run [selector]` — run scenarios (use selectors/tags to scope)
+
+Local probitas CLI tasks:
+
+- `probitas fmt` — format scenarios
+- `probitas lint` — lint scenarios
+- `probitas check` — type-check scenarios
+- `probitas run [selector]` — run scenarios (use selectors/tags to scope)
+
+## References to Share with AI
+
+- `/llms.txt` — sitemap for AI agents
+- `/docs/scenario/index.md` — scenario authoring guide
+- `/docs/client/index.md` — client usage
+- `/docs/expect/index.md` — assertion API
+- For API details use `deno doc` directly (preferred over Markdown):
+  - `deno doc jsr:@probitas/probitas`
+  - `deno doc jsr:@probitas/probitas/client/http`
+  - `deno doc jsr:@probitas/probitas/expect`
+
+## Links
+
+- Claude plugin marketplace: https://github.com/jsr-probitas/claude-plugins
+- Probitas plugin docs: https://github.com/jsr-probitas/claude-plugins/tree/main/plugins/probitas

data/docs.ts

@@ -16,6 +16,14 @@ export interface DocPage {
 }
 
 export const docPages: DocPage[] = [
+  {
+    path: "/AI/",
+    file: "./AI.md",
+    title: "AI Scenario Testing",
+    label: "AI",
+    description:
+      "How to have AI write and run Probitas scenario tests with Claude plugins",
+  },
   {
     path: "/docs/",
     file: "./docs/overview.md",

templates/home.tsx

@@ -187,6 +187,26 @@ function AiFriendlySection() {
             Example: /docs/index.md <i class="ti ti-arrow-right" />
           </a>
         </div>
+
+        <div class="ai-friendly-card">
+          <div class="ai-friendly-card-header">
+            <i class="ti ti-plug-connected" />
+            <span>Claude Plugins</span>
+          </div>
+          <p>
+            Official Claude Code plugin marketplace with the Probitas plugin
+            (scenario-writer agent, commands, and skills) for AI-assisted
+            authoring.
+          </p>
+          <a
+            href="https://github.com/jsr-probitas/claude-plugins"
+            class="ai-friendly-link"
+            target="_blank"
+            rel="noopener"
+          >
+            View marketplace repo <i class="ti ti-arrow-right" />
+          </a>
+        </div>
       </div>
     </section>
   );