potion-kit 0.0.1

package/.env.example

@@ -0,0 +1,20 @@
+# Potion-kit LLM config (copy to .env and set your keys)
+# See https://ai-sdk.dev for provider setup.
+
+# Provider: openai | anthropic
+POTION_KIT_PROVIDER=openai
+
+# Model id (optional; must be a chat model, not completion-only)
+# OpenAI: gpt-5.2, gpt-4o, gpt-3.5-turbo
+# Anthropic: claude-sonnet-4-5, claude-3-7-sonnet-latest
+# POTION_KIT_MODEL=gpt-5.2
+
+# API key for the chosen provider (set one)
+OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+
+# Optional: single key for any provider (fallback if OPENAI_API_KEY/ANTHROPIC_API_KEY not set)
+# POTION_KIT_API_KEY=
+
+# Optional: custom base URL (e.g. OpenAI-compatible proxy, LiteLLM, local model)
+# POTION_KIT_BASE_URL=

package/.husky/install.mjs

@@ -0,0 +1,23 @@
+/**
+ * Husky installer: run only when in a git repo (e.g. clone + npm install).
+ * Skip when installed from npm registry (no .git), in CI, or in production.
+ * See https://typicode.github.io/husky/how-to.html#ci-server-and-docker
+ */
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const hasGit = existsSync(resolve(packageRoot, ".git"));
+
+if (
+  !hasGit ||
+  process.env.CI === "true" ||
+  process.env.NODE_ENV === "production"
+) {
+  process.exit(0);
+}
+
+const { default: husky } = await import("husky");
+console.log(husky());

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 potion-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Potion Kit
+
+CLI to build websites with **HaroldJS** (haroldjs.com) and **UIPotion** (uipotion.com): static sites with Handlebars, Markdown, and SCSS only. Chat with the AI to design and build your site; the model uses the UIPotion catalog and HaroldJS conventions and can only suggest components from real specs.
+
+> **Note:** potion-kit is actively developed — we’re improving and optimizing it over time. For the best experience we recommend the **newest OpenAI or Anthropic models**; they handle the outcome quality best. Extensive use consumes API tokens and costs depend on your provider’s pricing. By using the tool you accept it as-is; only you decide whether and how much to use it. We hope you enjoy building with it.
+
+## Commands
+
+- **`potion-kit chat`** or **`potion-kit`** (default) — Interactive chat.
+- **`potion-kit chat "message"`** — Send one message and exit (one-shot).
+- **`potion-kit clear`** — Clear chat history for this project (next chat starts a new conversation).
+
+---
+
+## Usage (from npm)
+
+Use potion-kit as an installed CLI: run it from any directory where you have a `.env` with your LLM API key. No need to clone this repo.
+
+### Install
+
+**Option A — npx (no install):**
+
+```bash
+npx potion-kit chat
+```
+
+**Option B — global install:**
+
+```bash
+npm install -g potion-kit
+potion-kit chat
+```
+
+### Run in your project (or empty directory)
+
+1. **Go to the directory** where you want to work (new site or existing project). It can be an empty folder.
+
+   ```bash
+   mkdir my-site && cd my-site
+   ```
+
+2. **Create a `.env` file** in that directory with your LLM provider and API key. Minimal contents:
+
+   ```env
+   POTION_KIT_PROVIDER=openai
+   OPENAI_API_KEY=sk-your-key-here
+   ```
+
+   For Anthropic use `POTION_KIT_PROVIDER=anthropic` and `ANTHROPIC_API_KEY=...`. See [.env variables](#env-variables) for all options and [.env and security](#env-and-security).
+
+3. **Run potion-kit** from that same directory:
+
+   ```bash
+   npx potion-kit chat
+   # or, if installed globally:
+   potion-kit chat
+   ```
+
+   The tool reads `.env` from the **current working directory**, so always run `potion-kit` from the directory that contains your `.env` (and where you want the AI to read/write files).
+
+### Usage examples
+
+**Interactive chat (recommended):**
+
+```bash
+cd my-project
+npx potion-kit chat
+# or: potion-kit chat
+```
+
+Type your message at the `You:` prompt, press Enter; the model replies. Type `exit`, `quit`, or `q` (or Ctrl+C) to quit. Your conversation is saved for the next run.
+
+**One-shot (single message then exit):**
+
+```bash
+npx potion-kit chat "I want a blog with a header and footer"
+npx potion-kit chat "Add the navbar potion to the layout"
+```
+
+**Start a new conversation** (clear history for this directory):
+
+```bash
+npx potion-kit clear
+npx potion-kit chat "Let's build a docs site"
+```
+
+### Config
+
+Config is loaded in this order (later overrides earlier):
+
+1. **`.env` in the current working directory** (where you run potion-kit).
+2. **Environment variables** (e.g. `OPENAI_API_KEY`, `POTION_KIT_PROVIDER`).
+3. **`~/.potion-kit/config.json`** — provider and model only; **do not put API keys there**.
+
+#### .env variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `POTION_KIT_PROVIDER` | yes | `openai` or `anthropic` |
+| `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` | one required | API key for the chosen provider |
+| `POTION_KIT_MODEL` | no | Chat model id (defaults: `gpt-5.2` / `claude-sonnet-4-5`). Must be a **chat** model. |
+| `POTION_KIT_API_KEY` | no | Fallback key if provider-specific key is not set |
+| `POTION_KIT_BASE_URL` | no | Custom base URL (e.g. OpenAI proxy, LiteLLM) |
+
+**Minimal `.env`:**
+
+```env
+POTION_KIT_PROVIDER=openai
+OPENAI_API_KEY=sk-your-key-here
+```
+
+**With optional model:**
+
+```env
+POTION_KIT_PROVIDER=openai
+POTION_KIT_MODEL=gpt-5.2
+OPENAI_API_KEY=sk-your-key-here
+```
+
+#### .env and security
+
+- **potion-kit never sends `.env` or API keys to the model.** Keys are read only by the CLI and used for authentication with the LLM provider (OpenAI/Anthropic). They are not included in the system prompt, chat history, or any message content sent to the model. The only way a key could appear in the conversation is if you paste it yourself in a chat message — so don’t.
+- **Never commit `.env`.** It contains secrets. Add `.env` to your `.gitignore`. If the AI scaffolds a project for you, ensure `.env` is in that project’s `.gitignore` too.
+- **Never put API keys in `~/.potion-kit/config.json`.** That file is for provider and model only. Use `.env` or environment variables for keys.
+- **Never paste API keys in logs, issues, or chat.** If you paste a key into a chat message, it becomes part of the conversation and history.
+- **Where to put `.env`:** In the directory from which you run `potion-kit` (usually your project root). One `.env` per project.
+
+### Chat history
+
+Conversation is stored in **`.potion-kit/chat-history.json`** in the directory where you run `potion-kit chat`. The model uses it for context on the next run. Add `.potion-kit/` to `.gitignore` if you don’t want to commit chat history. Use `potion-kit clear` to reset history for that project.
+
+### Legal
+
+potion-kit uses [UIPotion](https://uipotion.com) specifications and catalog. **By using potion-kit you are using UIPotion’s service and agree to the [UIPotion legal disclaimer and privacy policy](https://uipotion.com/legal).** That page covers disclaimers on AI-generated code, liability, and user responsibility. Please read it before use.
+
+---
+
+## Development (potion-kit repo)
+
+For contributing to potion-kit or running from source.
+
+### Setup
+
+```bash
+git clone <repo>
+cd potion-kit
+npm install
+npm run build
+```
+
+### Run locally
+
+```bash
+node dist/index.js --help
+node dist/index.js chat
+```
+
+Put a `.env` in the repo (or in a test directory) and run from there. Copy `.env.example` to `.env` and set your API key.
+
+### Scripts
+
+- **`npm run build`** — Compile TypeScript to `dist/`.
+- **`npm run lint`** — ESLint on `src/`. `npm run lint:fix` to auto-fix.
+- **`npm run format`** — Prettier on `src/**/*.ts`. `npm run format:check` to only check.
+- **`npm run typecheck`** — `tsc --noEmit`.
+- **`npm run test`** — Run tests (Node built-in test runner; tests live in `test/`).

package/config.example.json

@@ -0,0 +1,4 @@
+{
+  "provider": "openai",
+  "model": "gpt-5.2"
+}

package/dist/ai/client.js

@@ -0,0 +1,97 @@
+/**
+ * Chat client using the Vercel AI SDK (https://ai-sdk.dev).
+ * Config drives which provider we use; tools are built-in (search_potions, get_potion_spec, get_harold_project_info, fetch_doc_page, write_project_file).
+ */
+import { generateText } from "ai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createPotionKitTools } from "./tools.js";
+const REQUEST_TIMEOUT_MS = 300_000; // 5 minutes (multi-step tool use can be slow)
+const MAX_STEPS = 16; // tool rounds (search, spec, read, write) plus a final text reply; scaffold can need many writes
+/**
+ * Create a chat that uses the AI SDK with the configured provider.
+ * send(messages) uses the first message as system if role is 'system', rest as messages.
+ * Tools (search_potions, get_potion_spec, get_harold_project_info, read_project_file, fetch_doc_page, write_project_file) are always available; multi-step so the model can call tools then reply.
+ */
+export function createChat(config, options = {}) {
+    const { onProgress, progressMessageBuilder, onError } = options;
+    const model = config.provider === "openai"
+        ? createOpenAI({ apiKey: config.apiKey, baseURL: config.baseUrl })(config.model)
+        : createAnthropic({ apiKey: config.apiKey })(config.model);
+    const tools = createPotionKitTools();
+    let stepCount = 0;
+    return {
+        async send(messages) {
+            stepCount = 0;
+            const system = messages.find((m) => m.role === "system")?.content;
+            const conversation = messages.filter((m) => m.role !== "system");
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+            try {
+                const result = await generateText({
+                    model,
+                    system: system ?? undefined,
+                    messages: conversation,
+                    tools,
+                    maxSteps: MAX_STEPS,
+                    maxTokens: 16_384, // per-step output limit; "length" finish = hit this before replying
+                    abortSignal: controller.signal,
+                    onStepFinish: (stepResult) => {
+                        stepCount++;
+                        if (onProgress) {
+                            const rawNames = stepResult.toolCalls?.map((t) => t.toolName) ?? [];
+                            const uniqueNames = [...new Set(rawNames)];
+                            const message = progressMessageBuilder
+                                ? progressMessageBuilder(stepCount, MAX_STEPS, uniqueNames)
+                                : `Step ${stepCount} (of up to ${MAX_STEPS})${uniqueNames.length ? ` — ${uniqueNames.join(", ")}` : " — Thinking"}…`;
+                            onProgress(message);
+                        }
+                    },
+                });
+                const text = result.text?.trim() ?? "";
+                if (text)
+                    return text;
+                const fromSteps = result.steps
+                    .map((s) => s.text?.trim())
+                    .filter(Boolean);
+                if (fromSteps.length) {
+                    const combined = fromSteps.join("\n\n");
+                    if (result.finishReason === "length") {
+                        return (combined +
+                            "\n\n[Reply was cut off by length limit; files may still have been created.]");
+                    }
+                    return combined;
+                }
+                // No text in any step: step limit or length; give a helpful fallback so the user isn't left with nothing
+                const stepsUsed = result.steps.length;
+                const hitStepLimit = result.finishReason === "tool-calls" || stepsUsed >= MAX_STEPS;
+                if (onError) {
+                    onError(hitStepLimit
+                        ? `Step limit reached (${stepsUsed} steps). The assistant may have created or updated files but didn't get to send a final message. Check your project and ask again if you want a summary or more changes.`
+                        : `potion-kit: model returned no text (finishReason: ${result.finishReason}, steps: ${stepsUsed}). Try asking again.`);
+                }
+                else {
+                    console.error(hitStepLimit
+                        ? `Step limit reached (${stepsUsed} steps). Check your project for changes.`
+                        : `potion-kit: model returned no text (finishReason: ${result.finishReason}, steps: ${stepsUsed}). Try asking again.`);
+                }
+                if (result.finishReason === "length") {
+                    return "The reply was cut off by the output length limit, but any file creation in earlier steps should have completed. Check your project for new files (e.g. under src/). You can run the build and ask for follow-up changes.";
+                }
+                if (hitStepLimit) {
+                    return "I hit the step limit while working on your project, so I didn't get to send a final message. Check your project for any files I created or updated (e.g. under src/). Run `npm run build` or `npm start` to try the site, and ask again if you want a summary or more changes.";
+                }
+                return "";
+            }
+            catch (err) {
+                if (err instanceof Error && err.name === "AbortError") {
+                    throw new Error(`Request timed out after ${REQUEST_TIMEOUT_MS / 60_000} minutes. Try again or use a shorter message.`);
+                }
+                throw err;
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        },
+    };
+}

package/dist/ai/context/harold.js

@@ -0,0 +1,100 @@
+/**
+ * Canonical "what the static site stack is and how it works" (HaroldJS).
+ * Injected into the system prompt so the model has real knowledge
+ */
+import { npmPackageLatestUrl } from "../endpoints.js";
+import { getJson } from "../remote.js";
+/** Fetch the latest harold-scripts version from npm; fallback to "latest" on error. */
+export async function getHaroldScriptsLatestVersion() {
+    const data = await getJson(npmPackageLatestUrl("harold-scripts"), {
+        timeoutMs: 5000,
+    });
+    if (!data || typeof data.version !== "string")
+        return "latest";
+    return `^${data.version}`;
+}
+const HAROLD_CONTEXT_TEMPLATE = `
+## STATIC SITE STACK (how it works)
+
+This is the only stack you use. All projects follow this structure and these conventions.
+
+### Config (project root: .haroldrc.json or package.json)
+- mdFilesDirName: directory for markdown files (default "posts"); also used in URLs (/posts/name).
+- mdFilesLayoutsDirName: directory for markdown layouts (default "blog-layouts").
+- outputDirName: build output directory (default "build").
+- hostDirName: optional subpath when hosting in a subdirectory.
+- minifyHtml, minifyCss: optional (default true).
+
+### Source layout (under src/)
+- pages/ — Handlebars pages (index.hbs, about.hbs). Output as .html at site root.
+- partials/ — Handlebars partials; include with {{> partialName}} or {{> head title="Page"}}. No underscore prefix in filenames (head.hbs, footer.hbs).
+- posts/ (or name from mdFilesDirName) — Markdown files. Output as .html under that path. Subdirs allowed; structure preserved in URLs.
+- blog-layouts/ (or from mdFilesLayoutsDirName) — Layouts for markdown; referenced in front matter as layout: 'layout-name'.
+- styles/ — SCSS/CSS. When scaffolding from zero use one main.scss only (no @import/@use). If the project already has multiple SCSS files or partials, keep that structure. harold-scripts compiles .scss/.css files that do not start with _.
+- assets/ — Images, JS, fonts; copied to build.
+- jsonData/ — Auto-generated (e.g. posts.json); do not hand-edit.
+- statics/ — Files copied to output root (robots.txt, manifest.json).
+
+### Markdown front matter (required)
+- layout — layout template name (string).
+- title — page title (string).
+- publicationDate — must be a valid YYYY-MM-DD string (e.g. 2025-01-15). Invalid or wrong-format dates break formatDate and the build.
+Optional: excerpt, tags (array), coverImage, and any custom fields (all passed to the layout). Use LF line endings; CRLF can break parsing.
+
+### Handlebars helpers (always use these)
+- {{relativePath 'path'}} — for ALL links and assets (so subdirectory hosting works). Never use absolute or root paths.
+- {{formatDate date=publicationDate format='dd mmmm yyyy'}} — dates. The date= value must be a valid date string (YYYY-MM-DD only), e.g. publicationDate from front matter or a literal like '2025-01-15'. Never use date='now' or any non-date string (it causes Invalid date). For copyright year use date='2025-01-01' format='yyyy'. Format options: dd, d, mmmm, mmm, mm, yyyy.
+- {{postsList perPageLimit=5 currentPage=1 byTagName="tag" className="..." dateFormat="dd mmmm yyyy" noTags= false noExcerpt= false noDate= false}} — render post lists from jsonData.
+- {{responsiveImg src="..." alt="..." width="..." height="..." loading="lazy"}} — responsive images.
+- {{hostDirName}} — for subdirectory-aware output (e.g. data-hrld-root="{{hostDirName}}").
+- Partials: {{> head}}, {{> footer}}, {{> partialName param="value"}}.
+
+### Pages (.hbs)
+- No DOCTYPE/html in page files (added by layout).
+- Always use {{> partialName}} for header/footer and {{relativePath '...'}} for links and assets.
+- Content in layout: {{{content}}} (triple braces for HTML from markdown).
+
+### Build process
+1. Prepare directories (build/, build/posts/).
+2. Copy assets (src/assets/ → build/assets/).
+3. Register Handlebars helpers and partials.
+4. Generate posts: Markdown + front matter → layout → HTML in build/posts/.
+5. Generate styles: SCSS → CSS → build/styles/.
+6. Generate pages: src/pages/*.hbs → HTML at build root.
+7. Copy jsonData and statics to build.
+Commands: npm run build (full build), npm start (build + dev server + watch, e.g. localhost:3000). These require package.json with harold-scripts (see scaffold below).
+
+### Complete project scaffold (when the site is new or missing root setup)
+If get_harold_project_info returns found: false, or the user has only src/ without a working build, create the full project so they can run npm install && npm run build.
+
+**1. package.json (project root)** — Required. Must include:
+- "scripts": { "build": "harold-scripts build", "start": "harold-scripts start" }
+- "devDependencies": { "harold-scripts": "<version>" } — always use the newest version (injected below).
+- "harold": { "mdFilesDirName": "posts", "mdFilesLayoutsDirName": "blog-layouts", "outputDirName": "build", "minifyHtml": true, "minifyCss": true }
+- "name", "version", "private": true as needed. Example:
+  {"name":"my-site","version":"1.0.0","private":true,"scripts":{"build":"harold-scripts build","start":"harold-scripts start"},"devDependencies":{"harold-scripts":"__HAROLD_SCRIPTS_VERSION__"},"harold":{"mdFilesDirName":"posts","mdFilesLayoutsDirName":"blog-layouts","outputDirName":"build","minifyHtml":true,"minifyCss":true}}
+
+**2. .gitignore (project root)** — Recommended. Include: build/, node_modules/, .env, .potion-kit/
+
+**3. File structure (when starting from nothing)** — Keep the standard layout. Do not use @import or @use in SCSS.
+
+- **src/styles/** — Create a single file main.scss with all styles in it. Do not add @import or @use; write plain SCSS/CSS only. No partials (_variables.scss etc.) when scaffolding from zero.
+- **src/partials/** — At least head.hbs and footer.hbs (pages use {{> head}} {{> footer}}).
+- **src/pages/** — At least index.hbs.
+- **src/assets/** — Can be empty; create a .gitkeep or one file if the dir must exist.
+- If the site will have a blog: src/posts/, src/blog-layouts/ with at least one layout.
+
+**4. SCSS rule (scaffolding only)** — When starting from zero files (harold not implemented yet), use one main.scss only: no @import, no @use. Put all styles in that single file so the build works. Once the user has split SCSS into multiple files or uses partials/@import/@use, accept that structure and do not force a single file.
+
+After creating package.json, tell the user to run: npm install && npm run build (or npm start for dev server).
+
+### Conventions and don'ts
+- File naming: kebab-case for posts/pages; partials without _ prefix. When scaffolding from zero use one main.scss only; if the project already uses multiple SCSS files or @import/@use, keep that structure.
+- Always use relativePath for href/src. Include excerpt and tags for SEO. Semantic HTML and a11y from UIPotion specs.
+- Do not edit files in build/ (generated). Do not skip required front matter. Do not use absolute paths. When talking to users, you may mention HaroldJS (haroldjs.com) and that the UI is based on UIPotion specs (uipotion.com).
+`;
+/** Harold context with the latest harold-scripts version injected for scaffold. */
+export async function getHaroldContext() {
+    const version = await getHaroldScriptsLatestVersion();
+    return HAROLD_CONTEXT_TEMPLATE.replace(/__HAROLD_SCRIPTS_VERSION__/g, version);
+}

package/dist/ai/context/index.js

@@ -0,0 +1,2 @@
+export { getHaroldContext, getHaroldScriptsLatestVersion } from "./harold.js";
+export { fetchPotionsIndex, formatPotionsCatalog, getPotionsCatalogText, } from "./potions-catalog.js";

package/dist/ai/context/potions-catalog.js

@@ -0,0 +1,70 @@
+/**
+ * Fetch the UIPotion index and return a text catalog so the model knows
+ * what potions exist and when to reach for them. Injected into the system prompt.
+ */
+import { potionsIndexUrl } from "../endpoints.js";
+import { getJson } from "../remote.js";
+/**
+ * Fetch potions-index.json from UIPotion. Returns null on network/parse error.
+ */
+export async function fetchPotionsIndex() {
+    return getJson(potionsIndexUrl);
+}
+const CATEGORY_ORDER = ["layouts", "components", "features", "patterns", "tooling"];
+/**
+ * Build a text catalog from the potions index for injection into the system prompt.
+ * Grouped by category so the model knows what's available and when to use each.
+ */
+export function formatPotionsCatalog(index) {
+    const potions = index.potions ?? [];
+    if (potions.length === 0) {
+        return "No UIPotion catalog available. Use search_potions and get_potion_spec tools to discover guides.";
+    }
+    const byCategory = new Map();
+    for (const p of potions) {
+        const cat = (p.category ?? "other").toLowerCase();
+        if (!byCategory.has(cat))
+            byCategory.set(cat, []);
+        byCategory.get(cat).push(p);
+    }
+    const lines = [
+        "## UI POTIONS (component and layout guides)",
+        "",
+        "You have access to these UIPotion guides. Use them when the user asks for a layout, component, feature, or pattern. When you need the full spec to generate code, call get_potion_spec(category, id) with the category and id below.",
+        "",
+    ];
+    for (const cat of CATEGORY_ORDER) {
+        const list = byCategory.get(cat);
+        if (!list?.length)
+            continue;
+        lines.push(`### ${cat}`);
+        for (const p of list) {
+            const excerpt = p.excerpt
+                ? ` — ${p.excerpt.slice(0, 80)}${p.excerpt.length > 80 ? "..." : ""}`
+                : "";
+            lines.push(`- **${p.id}**: ${p.name}${excerpt}`);
+        }
+        lines.push("");
+    }
+    const other = byCategory.get("other");
+    if (other?.length) {
+        lines.push("### other");
+        for (const p of other) {
+            lines.push(`- **${p.id}**: ${p.name}`);
+        }
+        lines.push("");
+    }
+    lines.push("When to reach for them: use **layouts** for full-page structure (dashboard, landing, docs); **components** for reusable UI (buttons, nav, cards, forms); **features** for complete flows (pricing, auth); **patterns** for interaction/design patterns; **tooling** for dev tooling. Always call get_potion_spec(category, id) to fetch the full JSON guide before generating code from a potion.");
+    return lines.join("\n");
+}
+/**
+ * Fetch the index and return the formatted catalog string for the system prompt.
+ * Use this when starting a chat session; cache the result if you want to avoid refetching.
+ */
+export async function getPotionsCatalogText() {
+    const index = await fetchPotionsIndex();
+    if (!index) {
+        return "UIPotion catalog could not be loaded. Use search_potions and get_potion_spec tools to discover and fetch guides.";
+    }
+    return formatPotionsCatalog(index);
+}

package/dist/ai/endpoints.js

@@ -0,0 +1,35 @@
+/**
+ * All remote endpoints used by potion-kit (npm, UIPotion, doc allowlist).
+ * Single source of truth for URLs and allowlisted hosts.
+ */
+/** npm registry base (no trailing slash). */
+export const NPM_REGISTRY_BASE = "https://registry.npmjs.org";
+/** UIPotion site base (no trailing slash). */
+export const UIPOTION_BASE = "https://uipotion.com";
+/** HaroldJS doc site hostnames (for fetch_doc_page allowlist). */
+export const DOC_ALLOWED_HOSTS = new Set([
+    "haroldjs.com",
+    "www.haroldjs.com",
+    "uipotion.com",
+    "www.uipotion.com",
+]);
+/** URL for a package's "latest" version in the npm registry. */
+export function npmPackageLatestUrl(packageName) {
+    return `${NPM_REGISTRY_BASE}/${packageName}/latest`;
+}
+/** URL for the UIPotion potions index JSON. */
+export const potionsIndexUrl = `${UIPOTION_BASE}/potions-index.json`;
+/** URL for a single potion spec JSON (category + id). */
+export function potionSpecUrl(category, id) {
+    return `${UIPOTION_BASE}/potions/${category}/${id}.json`;
+}
+/** Whether a URL is allowed for fetch_doc_page (haroldjs.com or uipotion.com only). */
+export function isDocUrlAllowed(url) {
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return DOC_ALLOWED_HOSTS.has(host);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/ai/fetch-doc.js

@@ -0,0 +1,72 @@
+/**
+ * Fetch a doc page or jsonData/posts.json from allowlisted domains only
+ * (haroldjs.com, uipotion.com). HaroldJS sites always generate jsonData/posts.json
+ * with the doc index (fileName, title, excerpt, etc.). The model can fetch that
+ * first, then open specific pages. Used as a fallback when info isn't in context
+ * or Potion specs.
+ */
+import { DOC_ALLOWED_HOSTS } from "./endpoints.js";
+import { get } from "./remote.js";
+const MAX_CHARS = 14_000;
+/**
+ * Strip HTML to rough plain text: remove script/style, then tags, collapse whitespace.
+ */
+function htmlToText(html) {
+    return html
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export async function fetchDocPage(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, error: "Invalid URL" };
+    }
+    if (!DOC_ALLOWED_HOSTS.has(parsed.hostname.toLowerCase())) {
+        return {
+            ok: false,
+            error: `URL must be from haroldjs.com or uipotion.com. Got: ${parsed.hostname}`,
+        };
+    }
+    try {
+        const res = await get(url);
+        if (!res.ok) {
+            return { ok: false, error: `HTTP ${res.status}` };
+        }
+        const contentType = res.headers.get("content-type") ?? "";
+        const isJson = parsed.pathname.endsWith("/jsonData/posts.json") || contentType.includes("application/json");
+        const raw = await res.text();
+        let text;
+        let title;
+        if (isJson) {
+            try {
+                const data = JSON.parse(raw);
+                text = JSON.stringify(data, null, 2);
+            }
+            catch {
+                text = raw;
+            }
+        }
+        else {
+            text = htmlToText(raw);
+            const titleMatch = raw.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+            if (titleMatch)
+                title = htmlToText(titleMatch[1]);
+        }
+        const truncated = text.length > MAX_CHARS ? text.slice(0, MAX_CHARS) + "\n...[truncated]" : text;
+        return { ok: true, title, text: truncated };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}