Kenobi Pages

Kenobi Pages lets an agent turn a user's messy intent into public page content. The agent does the setup, evidence capture, template authoring, workflow config, run, and verification. The user should mostly answer product questions and approve visible behavior.

First Response

Start with the user's real goal, not implementation nouns. Ask only what blocks the next useful action.

1. Say you will check setup and connected sources.
2. Run:

npx kenobi-pages doctor

3. If no API key is configured, offer both setup paths:
   • Interactive: "Run npx kenobi-pages init in your terminal so you do not paste the key here."
   • Agent-assisted: "Paste the key here and I will run npx kenobi-pages init --key ... --env-file .env.local."
4. If the CLI is not installed, ask permission to run it through npx. Do not make the user install it manually unless they prefer that.
5. When authenticated, inspect sources with:

npx kenobi-pages sources

Use the source list to ground the workflow conversation.

Where commands run

Do not assume your sandbox matches the user’s machine or project (missing .env.local, no API key, blocked outbound network). Misconfigured environments produce plain HTTP/ENOTFOUND/fetch failed errors or structured failures without Kenobi JSON — treat those as environment issues, not Kenobi bugs.

• Read-only commands are relatively safe to try anywhere (still useless without credentials): doctor, sources, sources sample, sources schema, hosted site list, hosted template list, hosted content list, hosted content get, hosted content verify, hosted publication list, workflow get, workflow explain, workflow validate, design-pack list, design-pack status, design-pack get, design-pack export, any --dry-run (workflow create/update, run).
• Mutating commands must run in the user’s real project where credentials exist — ask permission or ask them to run manually: init, evidence create, design-pack generate, hosted page create, hosted draft save, hosted publish, hosted content upsert, workflow create, workflow update, run (without --dry-run).
• Never run init from an isolated sandbox — it writes secrets to disk where the user may never see them.

Discovery before create

Before hosted page create or workflow create, list what already exists and ask whether to start fresh, adapt an existing page design, or inspect existing sites/templates/content/workflows first.

Example discovery commands:

npx kenobi-pages hosted site list
npx kenobi-pages hosted template list --full
npx kenobi-pages hosted content list --site <siteSlug> --template <templateSlug>

Show the user evidence before reuse: a previewUrl, a live URL, or the plain-language summary from workflow explain. Never silently overwrite or duplicate something live without approval.

Speak in product terms (and glossary)

Explain what happens for the user, not internal wiring. Use CLI nouns only in commands and JSON; use the glossary when talking to non-technical users.

Internal	Say this to the user
Template	Page design
Schema / ObjectSpec	Fields the page needs
Workflow	Automation
Source / dataSourceKey	Connected data
Source key	Which connected data to use
Destination / adapter	Where generated pages are saved
Publication	Live version
Content entry / content item	A page
Run	Generate a page
Params	Details you provide each time
Slug	URL ending
Site	Brand / website group
Evidence bundle	Brand snapshot
Design pack	Brand kit
Generation group	AI-written section
Binding (param / passthrough / generate)	Filled in by you / copied from your data / written by AI
Dry-run	Safe preview — no credit spend, no live writes

Trust the envelope (long-running commands)

For design-pack generate --wait and run (without --dry-run), the CLI polls until finished. Only the final JSON printed to stdout decides success — fields like ok, designPackStatus or runStatus, taskStatus, and nextCommand. Ignore intermediate stderr lines (poll events are JSON per line).

• If ok is true, run nextCommand exactly when present before telling the user the step is done (e.g. design-pack export …, or hosted content verify …).
• If the tool times out or disconnects, do not assume failure. Recover with:
  • Design pack: design-pack list <bundleId> or design-pack status <bundleId> <taskId>
  • Workflow run: GET the same run URL the CLI uses — npx kenobi-pages polls /api/v1/cortex/workflows/<workflowId>/runs/<runId>; re-fetch until terminal or use any run id you saved from the trigger response.

Default Product Judgment

Default to hosted pages unless the user already has a web app they want to own and maintain. Most users need Kenobi-hosted public URLs.

A "one-off page" can still use an internal hosted template and content item. Do not expose that detail unless it helps explain reuse or later edits.

Treat brand integrity as part of the job. If the user has a website, product page, or brand URL, create an evidence bundle and design pack before authoring TSX. If they have no URL, ask for any public page or brand reference.

Before creating or updating a workflow, explain the high-level wiring in user language, validate it with the CLI, and ask for approval. Miswired sources and destinations are the easiest way to produce plausible but wrong pages.

Core Workflow

Use this path for most hosted page requests:

1. Diagnose with doctor (read-only). Run init only in the user’s environment when needed (see Where commands run).
2. Discovery — list sites, templates, and relevant content; ask whether to start fresh, adapt an existing design, or inspect first (see Discovery before create).
3. Clarify outcome: hosted vs self-hosted, one-off vs reusable, audience, data source, brand source, and success criteria.
4. Capture brand evidence:

npx kenobi-pages evidence create <brand-url> --block-annoyances
npx kenobi-pages design-pack generate <bundleId> --wait
npx kenobi-pages design-pack export <bundleId> <designPackId>

Trust the final stdout envelope from generate --wait (ok, nextCommand) before export (see Trust the envelope).

5. Author template assets locally: TSX source, ObjectSpec schema JSON, and realistic preview content JSON.
6. Create the hosted page template:

npx kenobi-pages hosted page create \
  --site-slug <site> \
  --site-name "<Site Name>" \
  --template-slug <template> \
  --template-name "<Template Name>" \
  --source <template.tsx> \
  --schema <schema.json> \
  --content <preview-content.json> \
  --design-pack-id <designPackId>

7. Share the returned previewUrl and iterate.
8. Publish only after the user approves:

npx kenobi-pages hosted publish <templateIdOrSlug>
npx kenobi-pages sources schema hosted-pages:<templateSlug>

9. Create or run content:
   • Manual content: hosted content upsert
   • Workflow content: explain and validate automation in user language, ask approval, create it, dry-run the first generate if credits were not already approved, then run
10. Verify the public URL:

npx kenobi-pages hosted content verify <siteSlug> <templateSlug> <itemSlug>

When to Read References

• Read references/hosted-pages.md for hosted template authoring, manual hosted content, publish, preview, and URL verification.
• Read references/workflow-config.md before creating or editing Cortex workflow JSON.
• Read references/self-hosted-pages.md only when the user has an existing Next.js app or explicitly wants customer-owned hosting.

Working Rules

• Keep command output machine-readable. The CLI writes data JSON to stdout, progress to stderr, and errors as structured JSON to stderr.
• Parse CLI JSON instead of scraping text.
• Use fields for ObjectSpec objects. Do not write JSON Schema properties.
• Prefer deterministic CLI helpers (design-pack export, workflow scaffold, workflow explain) over inventing structure from memory.
• Use workflow explain --file <workflow.json> and workflow validate --name <name> --slug <slug> --file <workflow.json> before workflow create or workflow update; translate the explanation and validation errors/warnings for the user (see glossary).
• Use workflow create --dry-run or workflow update --dry-run when you want the exact server-side validation/impact response without writing.
• Keep generated project artifacts in a local .kenobi/pages/<page-or-template-slug>/ or .kenobi/workflows/ directory unless the user's project has a clearer convention.
• Ask before spending credits on AI runs or publishing a public page. If the user has not already approved credit spend for a run, execute run --dry-run first and summarize the returned impact.
• When a run fails, inspect the sanitized error first. Retry with run --debug only for developer/operator troubleshooting; production never exposes raw internal errors.
• After publishing or running, verify content through the CLI before telling the user the page is ready.

Useful Commands

Run full command help when unsure:

npx kenobi-pages --help

Common commands:

npx kenobi-pages doctor
npx kenobi-pages init --key <key> --env-file .env.local
npx kenobi-pages sources
npx kenobi-pages sources sample <sourceKey>
npx kenobi-pages hosted template list --full
npx kenobi-pages hosted publication list <templateIdOrSlug>
npx kenobi-pages hosted content list --site <siteSlug> --template <templateSlug>
npx kenobi-pages workflow explain --file .kenobi/workflows/<slug>.json
npx kenobi-pages workflow validate --name "<Workflow Name>" --slug <slug> --file .kenobi/workflows/<slug>.json
npx kenobi-pages run <workflowIdOrSlug> --dry-run --params-file params.json --context-file transcript.md
npx kenobi-pages run <workflowIdOrSlug> --params-file params.json --context-file transcript.md