LumiBase

⚡ The Content Operating System — Edge-Native, AI-Native, Agent-Operated

Documentation • Agent Setup • Community

---

🤖 AI Agent Setup

LumiBase is built to work natively with AI coding agents. Get your agent up to speed instantly:

# For any AI agent — paste this into your first message:
Read https://docs.lumibase.dev/en/agent-setup/prompt.md and follow the setup instructions.

Agent	Config file	Guide
Claude Code	CLAUDE.md (this repo)	claude-code.md
Cursor	.cursorrules (this repo)	cursor.md
GitHub Copilot	.github/copilot-instructions.md	github-copilot.md
OpenAI Codex	AGENTS.md (this repo)	codex.md
Windsurf	See guide	windsurf.md

LLM-friendly docs index: docs/llms.txt

---

🎯 What is LumiBase?

LumiBase is a Content Operating System (Content OS) — a runtime where AI agents operate content while humans set intent, taste, and accountability. A traditional CMS is a tool humans use to manipulate content. LumiBase inverts that: you declare the desired state of your content, and a control loop of governed agents converges toward it — continuously, with full provenance and human-held veto.

Built Edge-native on Cloudflare Workers for high-performance multi-website delivery, LumiBase pairs that delivery layer with an Agent Harness and an earned-autonomy trust model so automation is something agents earn, not something granted. Read the full thesis in docs/en/ai-native-vision.md.

CMS → Content OS: the unit of work shifts from operations (create item, edit field, publish) to intent (a declarative goal + constraints + budget); the operator shifts from editor-in-the-UI to agent-in-a-harness with a human reviewing exceptions; and content state shifts from static (correct at last edit) to live (continuously reconciled toward its SLO).

✨ Key Features

• Intent-driven operation: declare content SLOs (e.g. "every published product has ≥1 image, a 50–200 word description, and vi+en translations"); agents converge content toward them
• Reconciliation control loop: continuous drift detection + a reconciler that raises goals on drift and fixes them within a write budget
• Earned-autonomy trust ledger (L0–L4): per (site, agent, capability) autonomy from Shadow → Propose → Co-sign → Veto-window → Autopilot, with data-driven promotion, auto-demotion on incidents, and a four-scope kill switch
• Tenant Constitution: versioned, hashed publish-gate evaluators (rule DSL + LLM-judge); artifacts that fail the constitution never publish, at any autonomy level
• Provenance-first revisions: every revision records the agent/run/model, references, constitution hash, evaluation, and approver — exposed on the Delivery API via ?provenance=true
• Multi-agent newsroom: a role library with planner delegation, narrow per-role capability grants, and agent-as-reviewer gated approvals with a self-review ban
• Studio Mission Control: exception inbox, trust ledger, kill-switch UI, and per-field pin badges
• Edge-first + true multi-tenancy: Cloudflare Workers delivery, hard site_id isolation, page-hydration API, per-field AES-GCM encryption, and type-safe SDKs

Folder Structure (Turborepo)

lumibase/
├── apps/
│   ├── cms/                # Hono.js backend (Cloudflare Workers)
│   ├── studio/             # No-code admin SPA (React + Vite)
│   ├── docs/               # Vite docs viewer (Cloudflare Pages)
│   ├── landing/            # Next.js marketing site
│   ├── marketplace/        # Next.js marketplace site
│   └── consumer/           # Next.js delivery API demo
├── packages/
│   ├── database/           # Drizzle ORM schema + migrations
│   ├── shared/             # Types, zod schemas, policy DSL, field DSL
│   ├── sdk/                # JS SDK (REST + WS) + typegen core
│   ├── ui/                 # Shared shadcn components + CVA tokens
│   └── extension-sdk/      # Types/helpers for building extensions
├── docs/                   # Architecture + feature specs + roadmap
├── architecture.md         # Root summary (update on structural changes)
├── .cursorrules            # AI agent instructions
└── package.json

Quick start

pnpm install
pnpm --filter @lumibase/cms dev      # Hono API on :1989
pnpm --filter @lumibase/studio dev   # Studio SPA on :2026 (proxies /api → :1989)

The Studio placeholder dashboard pings /api/v1/utils/health to verify the wire-up. Full documentation lives in docs/; the task roadmap is in docs/en/roadmap/tasks.md. For production release operations, see the upgrade runbooks in English and Vietnamese.

Release policy

Every release must pass a green GitHub Actions CI run before it can be published or deployed. The required CI gate runs on every pull request and every push to main, and includes dependency installation with the locked pnpm version, version policy validation, typechecking, tests, lint for the current stable allowlist, and the production build.

Current release: v0.23.0 (2026-07-14) — Git integration, Change Feed schema capture, and relicense to Apache 2.0. Adds per-site GitHub/GitLab repository connections with PR/CI tracking, GitOps reconcile, and opt-in preview environments (migration 0009, PR #172); Change Feed now captures schema (DDL) changes and supports long-polling, plus a documented OpenAPI/SDK surface (migration 0008, PR #252); visitor/pageview counting and extension signing land as first-party modules (migrations 0010/0011, PR #261); and the project license changes from MIT to Apache License 2.0, effective this release — v0.22.0 remains the final MIT-licensed release. It builds on v0.22.0 (2026-07-12, CDC Change Feed end to end & realtime hardening — outbox capture, pull API, dispatcher, extension integration, retention, Studio surface, skills/MCP, migration 0007), v0.21.0 (2026-07-08, self-service auth realms & Cloudflare Pages pipeline repair — subscriber registration, rotating refresh tokens, per-realm session TTLs, migrations 0005/0006), v0.20.0 (backend + SDK gap-closing across 7 specs & high-load/cache readiness), v0.19.0 (CWE Top 100 closeout, Visual Flow Builder triggers & marketplace community features), v0.18.0 (custom domains & translation memory), v0.17.0 (lumibase_ table namespace & Content Releases), v0.16.0 (code-first configuration & auto-deploy from Flows), v0.15.0 (realtime audience plane & cosmic design system), v0.14.0 (push notifications & MCP path-traversal hardening), v0.13.0 (deployment integrations & cross-collection search), v0.12.0 (privacy & compliance suite, Directus-style interfaces & tenant isolation hardening), v0.11.0 (Insights, content versioning & tenant-scoped search), v0.10.0 (MCP everywhere), v0.9.0 (regulated/sensitive content readiness), and the v0.5.0 Content OS foundation — which remain the baseline this release builds upon, not replaces.

LUMIBASE_VERSION=0.23.0 docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod.yml up -d

See CHANGELOG.md for upgrade steps, rollback notes, compatibility details, and backup guidance.

Versioning

From v1.0.0, LumiBase follows strict Semantic Versioning: breaking changes to the public surface (REST/GraphQL API, @lumibase/sdk exports, response envelopes, header and env-var contracts, CLI/setup flags) require a major bump; features are additive in minors; deprecations run for at least one minor before removal. Security fixes cover the current and previous major for 6 months. Full rules: docs/en/contributing/versioning-policy.md. To report a vulnerability, see SECURITY.md.

Why port 1989?

LumiBase uses 1989 as its default CMS API port as a small tribute to the Web's origin story: in March 1989, Tim Berners-Lee wrote the proposal that became the World Wide Web. The same year also evokes walls coming down, which fits a headless CMS built to separate backend content infrastructure from frontend presentation.

---

Core Features

1. Edge-First: Runs entirely on Cloudflare Workers & Hyperdrive.
2. True Multi-Tenancy: Hard-coded site_id isolation.
3. Page Hydration API: Delivers layout and data in a single payload.
4. GitOps Ready: cms config:export for roles and schemas.
5. Agent Harness: Govern AI agents with goals, context, capabilities, approvals, evaluations, and artifact commits.

---

📚 AI Skills Documentation

For detailed AI-assisted development guidance, including database architecture patterns, edge optimization strategies, and UI/UX integration patterns, see docs/ai-skills.md. This comprehensive guide provides the prompts and patterns used to accelerate LumiBase development with AI assistance.

---

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Inspired by Directus
• Built with Cloudflare
• UI components from shadcn/ui

---

⭐ If you find this project helpful, please consider giving it a star!

Made with ❤️ by Khuepm