@ignite-agent/agent 0.1.0 → 0.4.1

package/dist/types.d.ts

@@ -36,3 +36,42 @@ export type MetadataDirective = {
         images?: string[];
     };
 };
+export type FeedPage = {
+    slug: string;
+    kind: 'wiki' | 'article';
+    path: string;
+    title: string;
+    html: string;
+    updatedAt: string;
+    indexable: boolean;
+    excerpt?: string | null;
+    publishedAt?: string | null;
+    parent?: {
+        slug: string;
+        title: string;
+        path: string;
+    } | null;
+    author?: {
+        name: string;
+        url?: string | null;
+        image?: string | null;
+    } | null;
+    image?: {
+        url: string;
+        alt?: string | null;
+        width?: number | null;
+        height?: number | null;
+    } | null;
+    images?: Array<{
+        url: string;
+        alt?: string | null;
+    }> | null;
+    datePublished?: string | null;
+    dateModified?: string | null;
+    lastReviewed?: string | null;
+};
+export type FeedIndex = {
+    generatedAt: string;
+    version: string;
+    pages: FeedPage[];
+};

package/onboarding/CLAUDE-CODE-SETUP.md

@@ -1,51 +1,85 @@
 # Set up Ignite in this Next.js app (Claude Code prompt)
 
-Paste the block below to Claude Code (or any coding agent) from the root of your Next.js App Router project. It
-wires in `@ignite-agent/agent` and verifies the build. You need your Ignite site id and site token first — get them by
+Paste the block below to Claude Code from the root of your Next.js App Router project. It wires in
+`@ignite-agent/agent` and verifies the build. You need your Ignite site id and site token first — get them by
 running `npx ignite connect`, or from your Ignite workspace.
 
+`AGENTS.md` in the package is the source of truth. This file is the copy-paste prompt.
+
 ---
 
-You are setting up the `@ignite-agent/agent` package in this Next.js App Router project. Do the following, then stop
-and report what changed.
+You are setting up the `@ignite-agent/agent` package in this Next.js App Router project. Follow this exactly,
+then stop and report what changed.
+
+Hard rules:
+- Server-only. Never `"use client"` on Ignite routes. Never fetch Ignite from the browser.
+- Env vars are `IGNITE_SITE_ID` and `IGNITE_SITE_TOKEN`. Never `NEXT_PUBLIC_IGNITE_SITE_TOKEN`.
+- Do not invent client-side fetching or MCP calls from React.
+- Additive: if a target file already exists, show it and skip. Do not overwrite robots, sitemap, proxy,
+  middleware, or layout without asking.
+- Never delete or replace an existing blog or wiki. If `app/blog` or `app/w` already has host pages, wrap
+  them (`tryLoadFeedPage` + `mergeSlugs`, local slugs win). Do not write the one-line Ignite re-export over
+  those files. See `onboarding/MIGRATE-EXISTING.md`.
+- Use `app/` or `src/app/` according to this repo. Put `proxy.ts` / `middleware.ts` at the project root.
 
-1. Confirm this is a Next.js App Router project (an `app/` directory, `next` in `package.json`). If it is a Pages
-   Router project, stop and tell me — this setup targets the App Router.
+1. Confirm this is a Next.js App Router project (`app/` or `src/app/`, `next` in `package.json`). If it is a
+   Pages Router project, stop and tell me.
 
-2. Install the package: `npm install @ignite-agent/agent` (use the project's package manager if it isn't npm).
+2. Install the package with this project's package manager (`npm install @ignite-agent/agent`, or pnpm/yarn/bun).
 
 3. Add the site credentials to `.env.local` (create it if missing), using the values I give you:
    ```
    IGNITE_SITE_ID=...
    IGNITE_SITE_TOKEN=...
    ```
-   Never hardcode these in source. If the project deploys on Vercel or similar, remind me to set the same two
-   environment variables there.
+   Never hardcode these in source. Remind me to set the same two in Vercel / the host.
 
-4. Create `app/robots.ts` with exactly:
+4. Create these files (skip and show if they already exist):
    ```ts
+   // app/robots.ts   (or src/app/robots.ts)
    export { default } from '@ignite-agent/agent/robots'
    ```
-   If `app/robots.ts` already exists, show me its contents and ask before replacing.
-
-5. Create `app/sitemap.ts` with exactly:
    ```ts
+   // app/sitemap.ts
    export { default } from '@ignite-agent/agent/sitemap'
    ```
-   Same rule if it already exists.
+   ```ts
+   // app/w/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // app/w/page.tsx
+   export { WikiIndex as default, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // app/blog/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/blog'
+   ```
+   ```ts
+   // app/blog/page.tsx
+   export { BlogIndex as default, revalidate } from '@ignite-agent/agent/blog'
+   ```
 
-6. In `app/layout.tsx`, import and render the JSON-LD component inside `<head>` (or at the top of `<body>` if the
-   layout has no explicit `<head>`):
+5. In `app/layout.tsx` (or `src/app/layout.tsx`), import and render JSON-LD inside `<head>` (or at the top of
+   `<body>` if the layout has no explicit `<head>`):
    ```tsx
    import { IgniteJsonLd } from '@ignite-agent/agent/jsonld'
    // ...
    <IgniteJsonLd />
    ```
 
-7. (Optional, recommended) Create `proxy.ts` at the project root with:
+6. Crawl logging, optional. If `package.json` has Next 15, create `middleware.ts` at the project root:
+   ```ts
+   export { middleware, config } from '@ignite-agent/agent/proxy'
+   ```
+   If Next 16+, create `proxy.ts` at the project root:
    ```ts
    export { proxy, config } from '@ignite-agent/agent/proxy'
    ```
    If a `proxy.ts` or `middleware.ts` already exists, do NOT overwrite it — show it to me and we will merge.
 
-8. Run the build (`npm run build`) and report any errors. Do not change unrelated files.
+7. Brand, optional. If a global CSS file exists and does not already define `--ignite-color-text`, append the
+   mapping from the package README (shadcn uses `hsl(var(--foreground))`; full colors like oklch/hex use
+   `var(--foreground)`). Or run `npx ignite init` and let it write routes + the mapping.
+
+8. Run `npx ignite doctor` if possible, then the project build. Report errors. Do not change unrelated files.

package/onboarding/CURSOR-SETUP.md

@@ -0,0 +1,73 @@
+# Set up Ignite in this Next.js app (Cursor prompt)
+
+Paste the block below into Cursor Agent from the root of your Next.js App Router project. You need your Ignite
+site id and site token first (`npx ignite connect`, or from your Ignite workspace).
+
+You can also save this prompt as `.cursor/rules/ignite.mdc`. `AGENTS.md` in the package is the source of truth.
+
+---
+
+You are setting up `@ignite-agent/agent` in this Next.js App Router project. Follow this exactly, then stop and
+report what changed.
+
+Hard rules:
+- App Router only (`app/` or `src/app/`). Pages Router → stop.
+- Server-only. No `"use client"` on Ignite routes. No `fetch` of the Ignite API from the browser.
+- `.env.local`: `IGNITE_SITE_ID` and `IGNITE_SITE_TOKEN`. Never `NEXT_PUBLIC_IGNITE_SITE_TOKEN`.
+- Do not call MCP (`npx ignite mcp`) from React. MCP is for the editor, not the app.
+- If a target file already exists, show it and skip. Do not overwrite robots, sitemap, proxy, middleware, or
+  layout without asking.
+- Never delete or replace an existing blog or wiki. Wrap host `/blog` and `/w` routes (`tryLoadFeedPage` +
+  `mergeSlugs`, local slugs win). See `onboarding/MIGRATE-EXISTING.md`.
+
+1. Confirm App Router (`app/` or `src/app/`, `next` in `package.json`).
+
+2. Install with this repo's package manager: `npm install @ignite-agent/agent` (or pnpm/yarn/bun).
+
+3. Write `.env.local` (create if missing) with the values I provide:
+   ```
+   IGNITE_SITE_ID=...
+   IGNITE_SITE_TOKEN=...
+   ```
+   Remind me to set the same two in Vercel / the host. Do not commit `.env.local`.
+
+4. Create these files under `app/` or `src/app/` to match the repo:
+   ```ts
+   // robots.ts
+   export { default } from '@ignite-agent/agent/robots'
+   ```
+   ```ts
+   // sitemap.ts
+   export { default } from '@ignite-agent/agent/sitemap'
+   ```
+   ```ts
+   // w/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // w/page.tsx
+   export { WikiIndex as default, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // blog/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/blog'
+   ```
+   ```ts
+   // blog/page.tsx
+   export { BlogIndex as default, revalidate } from '@ignite-agent/agent/blog'
+   ```
+
+5. In the root `layout.tsx`, render JSON-LD in `<head>` (or the top of `<body>`):
+   ```tsx
+   import { IgniteJsonLd } from '@ignite-agent/agent/jsonld'
+   <IgniteJsonLd />
+   ```
+
+6. Optional crawl logging. Next 15: project-root `middleware.ts` exporting `{ middleware, config }` from
+   `@ignite-agent/agent/proxy`. Next 16+: project-root `proxy.ts` exporting `{ proxy, config }`. Do not
+   overwrite an existing file.
+
+7. Optional brand. If `globals.css` has no `--ignite-color-text`, append the README mapping (shadcn:
+   `hsl(var(--foreground))`; oklch/hex: `var(--foreground)`). `npx ignite init` does routes + this mapping.
+
+8. Run `npx ignite doctor`, then the project build. Report errors. Do not change unrelated files.

package/onboarding/LOVABLE-SETUP.md

@@ -0,0 +1,76 @@
+# Set up Ignite in this Next.js app (Lovable prompt)
+
+Paste the block below into Lovable. This package is **Next.js App Router and server-only**. If this Lovable
+project is not Next.js App Router, stop — do not install it on a Vite SPA.
+
+You need your Ignite site id and site token (`npx ignite connect`, or from your Ignite workspace).
+
+`AGENTS.md` in the package is the source of truth.
+
+---
+
+Set up `@ignite-agent/agent` in this project. Follow this exactly. Then stop and list every file you changed.
+
+Hard rules (do not break these):
+- This package is server-only. Do not add `"use client"` to any Ignite route.
+- Do not fetch `app.igniteagent.ai` from the browser. Do not put the token in any `NEXT_PUBLIC_*` variable.
+- Do not use MCP in the app. Do not add axios/SWR/React Query for Ignite.
+- If this project is Vite, Remix, or Pages Router, stop and say so. Do not invent a client integration.
+- If a target file already exists, show it and skip. Do not overwrite it.
+- Never delete or replace an existing blog or wiki. Wrap host `/blog` and `/w` routes (`tryLoadFeedPage` +
+  `mergeSlugs`, local slugs win). See `onboarding/MIGRATE-EXISTING.md`.
+
+1. Confirm Next.js App Router: `app/` or `src/app/` exists, and `next` is in `package.json`.
+
+2. Install: `npm install @ignite-agent/agent` (use the project's package manager).
+
+3. Put secrets in the project's **server** environment (Lovable / host env UI and `.env.local` if the repo uses
+   it). Names:
+   ```
+   IGNITE_SITE_ID=...
+   IGNITE_SITE_TOKEN=...
+   ```
+   I will paste the values. Never print the token back in full in chat after writing it.
+
+4. Create these files under `app/` or `src/app/` (whichever this repo uses):
+   ```ts
+   // robots.ts
+   export { default } from '@ignite-agent/agent/robots'
+   ```
+   ```ts
+   // sitemap.ts
+   export { default } from '@ignite-agent/agent/sitemap'
+   ```
+   ```ts
+   // w/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // w/page.tsx
+   export { WikiIndex as default, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // blog/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/blog'
+   ```
+   ```ts
+   // blog/page.tsx
+   export { BlogIndex as default, revalidate } from '@ignite-agent/agent/blog'
+   ```
+   Leave those files as one-line re-exports. Do not restyle them in the route file.
+
+5. In the root layout, render:
+   ```tsx
+   import { IgniteJsonLd } from '@ignite-agent/agent/jsonld'
+   <IgniteJsonLd />
+   ```
+   inside `<head>` if present, otherwise at the top of `<body>`.
+
+6. Optional: Next 15 → `middleware.ts` at the project root exporting `{ middleware, config }` from
+   `@ignite-agent/agent/proxy`. Next 16+ → `proxy.ts` exporting `{ proxy, config }`. Skip if that file exists.
+
+7. Optional brand: if global CSS exists and has no `--ignite-color-text`, map host colors using the package
+   README. shadcn HSL channels need `hsl(var(--foreground))`. Full colors use `var(--foreground)`.
+
+8. Run the production build. Fix only errors caused by this setup. Report what you created and whether the
+   build passed.

package/onboarding/MIGRATE-EXISTING.md

@@ -0,0 +1,94 @@
+# Keep existing blog / wiki routes
+
+`npx ignite init` never overwrites `app/blog/**` or `app/w/**` if those files already exist.
+Your posts stay. Ignite pages fill slugs the host does not already serve.
+
+Collision rule: **local slug wins.** If both the host and the Hub have `/blog/hello`, the host page
+renders. Do not delete host files. Do not re-export over them.
+
+## Page route (blog)
+
+Rename nothing. Edit the existing `app/blog/[slug]/page.tsx` (or `src/app/...`) to try the local
+loader first, then the Hub:
+
+```tsx
+import { notFound } from 'next/navigation'
+import {
+  FeedArticle,
+  feedPageMetadata,
+  generateStaticParams as igniteParams,
+  mergeSlugs,
+  revalidate,
+  tryLoadFeedPage,
+} from '@ignite-agent/agent/blog'
+
+export { revalidate }
+
+export async function generateStaticParams() {
+  const local = await localSlugs()
+  return mergeSlugs(local, await igniteParams())
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  const local = await loadLocal(slug)
+  if (local) return localMetadata(local)
+  const page = await tryLoadFeedPage('article', slug)
+  return page ? feedPageMetadata(page) : {}
+}
+
+export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  const local = await loadLocal(slug)
+  if (local) return <ExistingPost post={local} />
+  const page = await tryLoadFeedPage('article', slug)
+  if (!page) notFound()
+  return <FeedArticle page={page} />
+}
+```
+
+Replace `localSlugs` / `loadLocal` / `ExistingPost` / `localMetadata` with the loaders you already
+have. Wiki is the same with `@ignite-agent/agent/wiki` and `tryLoadFeedPage('wiki', slug)`.
+
+## Index route
+
+If `app/blog/page.tsx` already lists your posts, keep it. Render Hub articles underneath (or in a
+second section). Do not replace the page with `BlogIndex as default`.
+
+```tsx
+import { BlogIndex } from '@ignite-agent/agent/blog'
+
+export default async function Blog() {
+  return (
+    <main>
+      <ExistingIndex />
+      <BlogIndex />
+    </main>
+  )
+}
+```
+
+`BlogIndex` returns `null` when the Hub has no articles, so an empty feed does not blank the page.
+
+## Sitemap
+
+If `app/sitemap.ts` already exists, leave it. `igniteSitemap()` already includes published wiki/blog
+URLs. Merge them into the host list; do not drop local URLs.
+
+```ts
+import igniteSitemap, { mergeSitemap } from '@ignite-agent/agent/sitemap'
+
+export default async function sitemap() {
+  const local = await localSitemap()
+  return mergeSitemap(local, await igniteSitemap())
+}
+```
+
+Set `IGNITE_SITE_URL` so Ignite locs are absolute (`https://yourdomain.com/w/...`).
+
+## What not to do
+
+- Do not delete `app/blog` or `app/w`.
+- Do not write the one-line Ignite re-export over a host page.
+- Do not fetch the Hub from a Client Component to "merge" feeds.
+- Do not invent Hub slugs that copy local posts. New Ignite pages need unused slugs.

package/onboarding/REPLIT-SETUP.md

@@ -0,0 +1,76 @@
+# Set up Ignite in this Next.js app (Replit Agent prompt)
+
+Paste the block below into Replit Agent from the Next.js App Router Repl. Put the Ignite site token in
+**Secrets**, not in client code.
+
+You need your Ignite site id and site token (`npx ignite connect`, or from your Ignite workspace).
+
+`AGENTS.md` in the package is the source of truth.
+
+---
+
+Set up `@ignite-agent/agent` in this Repl. Follow this exactly, then stop and report what changed.
+
+Hard rules:
+- Next.js App Router only (`app/` or `src/app/`). If this Repl is not that, stop.
+- Server-only. No `"use client"` on Ignite files. No `fetch` of Ignite from the browser.
+- Secrets: `IGNITE_SITE_ID` and `IGNITE_SITE_TOKEN` in Replit Secrets (and `.env.local` if the Repl uses it).
+  Never `NEXT_PUBLIC_IGNITE_SITE_TOKEN`. Never put the token in `index.html` or a client component.
+- Do not use MCP inside the web app.
+- If a target file already exists, show it and skip.
+- Never delete or replace an existing blog or wiki. Wrap host `/blog` and `/w` routes (`tryLoadFeedPage` +
+  `mergeSlugs`, local slugs win). See `onboarding/MIGRATE-EXISTING.md`.
+
+1. Confirm App Router (`app/` or `src/app/`, `next` in `package.json`).
+
+2. Install with the Repl's package manager: `npm install @ignite-agent/agent`.
+
+3. Set Secrets (Replit sidebar → Secrets), names exactly:
+   ```
+   IGNITE_SITE_ID=...
+   IGNITE_SITE_TOKEN=...
+   ```
+   I will paste the values. Also write `.env.local` with the same two if the project already uses dotenv.
+   Do not commit secrets.
+
+4. Create these files under `app/` or `src/app/`:
+   ```ts
+   // robots.ts
+   export { default } from '@ignite-agent/agent/robots'
+   ```
+   ```ts
+   // sitemap.ts
+   export { default } from '@ignite-agent/agent/sitemap'
+   ```
+   ```ts
+   // w/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // w/page.tsx
+   export { WikiIndex as default, revalidate } from '@ignite-agent/agent/wiki'
+   ```
+   ```ts
+   // blog/[slug]/page.tsx
+   export { default, generateStaticParams, generateMetadata, revalidate } from '@ignite-agent/agent/blog'
+   ```
+   ```ts
+   // blog/page.tsx
+   export { BlogIndex as default, revalidate } from '@ignite-agent/agent/blog'
+   ```
+
+5. In the root layout, add JSON-LD in `<head>` (or top of `<body>`):
+   ```tsx
+   import { IgniteJsonLd } from '@ignite-agent/agent/jsonld'
+   <IgniteJsonLd />
+   ```
+
+6. Optional crawl logging. Next 15: project-root `middleware.ts` exporting `{ middleware, config }` from
+   `@ignite-agent/agent/proxy`. Next 16+: project-root `proxy.ts` exporting `{ proxy, config }`. Do not
+   overwrite an existing file.
+
+7. Optional brand. If `globals.css` has no `--ignite-color-text`, append the README mapping. Or run
+   `npx ignite init`.
+
+8. Run `npx ignite doctor` if the CLI is available, then the Repl build. Report errors. Do not change
+   unrelated files.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@ignite-agent/agent",
-  "version": "0.1.0",
-  "description": "Ignite for Next.js: a drop-in App Router SDK for robots, sitemap, JSON-LD, metadata, crawl logging, and the approve-and-apply change loop, driven by your Ignite workspace.",
+  "version": "0.4.1",
+  "description": "Ignite for Next.js: App Router SDK for robots, sitemap, JSON-LD, metadata, crawl logging, and hosted wiki/blog pages. Server-only. The front end reads JSON; MCP is for coding agents, not the browser.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -16,7 +16,13 @@
   },
   "files": [
     "dist",
-    "onboarding"
+    "onboarding",
+    "LICENSE",
+    "AI.txt",
+    "dist/ignite.css",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map"
   ],
   "exports": {
     ".": "./dist/index.js",
@@ -25,20 +31,28 @@
     "./jsonld": "./dist/operator/jsonld.js",
     "./metadata": "./dist/operator/metadata.js",
     "./proxy": "./dist/operator/proxy.js",
-    "./client": "./dist/client.js"
+    "./wiki": "./dist/operator/wiki.js",
+    "./blog": "./dist/operator/blog.js",
+    "./client": "./dist/client-public.js",
+    "./styles.css": "./dist/ignite.css"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node scripts/write-css.mjs",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --test dist/**/*.test.js"
+    "test": "npm run build && node --test dist/client.test.js dist/mcp.test.js dist/operator/ui.test.js dist/operator/sitemap-merge.test.js dist/cli/project.test.js"
+  },
+  "dependencies": {
+    "server-only": "^0.0.1"
   },
   "peerDependencies": {
     "next": ">=15.0.0 <17.0.0",
     "react": ">=18.2.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true }
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -47,5 +61,14 @@
     "react": "^19.0.0",
     "typescript": "^5.6.0"
   },
-  "keywords": ["ignite", "nextjs", "app-router", "robots", "sitemap", "json-ld", "metadata", "ai-search", "llm"]
+  "keywords": [
+    "ignite",
+    "nextjs",
+    "app-router",
+    "robots",
+    "sitemap",
+    "json-ld",
+    "metadata",
+    "ai-search"
+  ]
 }