0B6OS Documentation

Start Here

0B6OS is a SvelteKit starter template for Cloudflare. Create your own repository with Use this template, then run bun run customize to rename the app, the slug, the dev port, and the Cloudflare resource names in one pass — CUSTOMIZE.md covers the steps a script cannot do.

Start locally with an isolated D1 database, then connect the production Cloudflare resources only when you are ready to deploy.

1. Create your repository from the template and run the customization pass.
2. Install the frozen Bun dependency graph.
3. Apply database migrations locally.
4. Run the app and verify the setup, login, CMS, and chat surfaces.
5. Configure OAuth and owner access through the setup flow.
6. Keep every coverage metric at or above the enforced 95% floor.
7. Create project-owned Cloudflare bindings before building or deploying remotely.

Quick Start

Bun is the recommended default for this repository. Run the commands below, then open http://localhost:3160.

								
									# Install dependencies
								
							
								
									$
									bun install
								
							
								
									
								
							
								
									# Start development server
								
							
								
									$
									bun run dev
								
							
								
									
								
							
								
									# Apply local D1 migrations
								
							
								
									$
									bun run db:migrate:local
								
							
								
									
								
							
								
									# Build for production
								
							
								
									$
									bun run build
								
							
								
									
								
							
								
									# Type-check and tests
								
							
								
									$
									bun run check
								
							
								
									$
									bun run test
								
							
								
									
								
							
								
									# Coverage report
								
							
								
									$
									bun run test:coverage
								
							
								
									
								
							
								
									# Deploy to Cloudflare Pages
								
							
								
									$
									bun run deploy
								
							

What You Get Out of the Box

0B6OS integrates its main product surfaces as one Cloudflare-native application: identity, content management, AI workflows, administration, analytics, and agent-ready publishing.

How To Use the App

Use the app in this order if you want the least confusing first run. That sequence matches how the repo is structured and avoids most setup-related false alarms.

1. Open /setup first on a fresh environment and configure owner credentials.
2. Complete /setup before expecting sign-in or AI features to work.
3. Sign in through /auth/login or create an account through /auth/signup.
4. Open the command palette with Ctrl/Cmd + K to move between major routes quickly.
5. Use /chat for AI interactions, /profile for account settings, and /admin for operator tasks.
6. Use the theme toggle to verify light, dark, and system-preference presentation.

Drag and Drop

<WidgetBoard> takes a layout and a list of columns, and reports a new layout through on:change. It stores nothing itself, so where a layout is saved stays your decision.

<WidgetBoard bind:widgets {columns} on:change={(e) => save(e.detail.widgets)} />

Registering a widget takes three edits and none of them is the board: an entry in src/lib/widgets/manifest.ts, a line in src/lib/widgets/index.ts, and the component itself. The registry ships empty on purpose. The two actions underneath the board — use:draggable and use:dropzone — work on any markup, so a sortable list or a nav reorder needs no board at all.

Keyboard control

Every pointer gesture has a keyboard equivalent, announced through a live region. Focus a drag handle, then:

• Space or Enter — pick the widget up, and put it down again.
• Arrow up and down — move it within its column.
• Arrow left and right — move it to the column either side.
• Escape — cancel, returning it to where it started.

On a touchscreen, hold a handle briefly before dragging — a swipe stays a swipe, so the page still scrolls. Dragging near the top or bottom edge scrolls the page with you.

The rule that will bite you

A widget's stored state must be inert. A value that changes on a timer — a price, a clock, a connection count — goes out through the widget's live event and comes back in through the board's live prop; it must never be written into widget.title, which is persisted. Ignoring this is how a dashboard rewrites its whole layout every thirty seconds and burns a day's storage quota from one open tab.

Full reference, including the reorder contract and the component checklist: docs/WIDGET_BOARD.md.

Working With AI in This Repo

Treat AI as a fast pair programmer, not as a source of truth. It is useful here because the repo already includes app structure, tests, and strong conventions, which gives the assistant real context to work against.

If you are using an AI coding agent, keep requests concrete: mention the page or failing test, state the desired behavior, and ask for the smallest validating change that solves it.

Core Commands

These scripts are defined in package.json and are the canonical local workflow.

Cloudflare Bindings

0B6OS is configured for Cloudflare Pages with these bindings in wrangler.toml:

• DB as D1 database binding (database name: ob6os-db).
• KV as KV namespace for runtime config and flags.
• BUCKET as R2 bucket binding.
• Queue producer binding is documented but commented out by default.

Set app secrets in Cloudflare dashboard or Wrangler secrets for production. Avoid committing raw secrets to source control.

Database Migrations

Migrations are ordered SQL files under migrations/ and tracked by D1. Never edit or delete existing migration files once committed to main.

# Apply pending migrations to local D1
bun run db:migrate:local

# Apply pending migrations to remote D1
bun run db:migrate

# List migration status
bun run db:migrate:list

When schema changes are needed, create a new file with the next sequence number (for example, 0012_add_feature_flag.sql) and use ALTER TABLE or new CREATE statements.

Authentication and Setup Flow

Authentication is built into this app on a setup-first workflow — no third-party auth library sits in the request path. The browser receives an unsigned opaque session token (random, worthless without its server-side record — its SHA-256 digest is the lookup key), while the revocable session record, identity, and roles are loaded from D1 on every request. Authentication fails closed if D1 or SESSION_SECRET is unavailable.

You can sign in with email and password, or with GitHub and Discord once those providers are configured. The main routes are /setup, /auth/login, /auth/signup, and /reset.

Admin Analytics

/admin/stats is the built-in analytics surface: traffic over a 1, 7, 30, or 90-day window, views by route, the most-read CMS items, referrers, countries, an audience breakdown, and user and content growth over time. It is first-party — there is no third-party script, no account, and no API key to provision.

Everything collected is a daily aggregate counter in D1. There are no cookies, no identifiers, and no IP addresses anywhere in the feature. The User-Agent is read to classify the request and then discarded, so only coarse buckets (operating system, browser, device, language, viewport) are ever stored, and country comes from the Cloudflare edge rather than from an IP lookup. Because nothing per-visitor is retained, this needs no consent banner.

UPDATE users SET can_view_stats = 1 WHERE email = '[email protected]';

curl -X POST https://your-app/api/cron/prune-view-stats \
  -H "Authorization: Bearer $CRON_SECRET"

Testing and Quality Gates

0B6OS follows Test-Driven Development. Write failing tests first, then implementation, then refactor.

# Run all tests
bun run test

# Run tests in watch mode
bun run test:watch

# Check coverage
bun run test:coverage

# Run E2E tests
bun run test:e2e

# Run all tests (unit + E2E)
bun run test:all

Vitest enforces a 95% floor for lines, statements, functions, and branches. A change is not ready when any metric falls below that threshold.

Project Structure

0B6OS/
├── .github/              # Copilot and workflow instructions
├── src/
│   ├── lib/
│   │   ├── components/     # Reusable UI components
│   │   ├── services/       # Business logic
│   │   ├── stores/         # Svelte stores
│   │   ├── types/          # Shared type definitions
│   │   └── utils/          # Helpers
│   ├── routes/             # SvelteKit routes
│   │   ├── api/            # API endpoints
│   │   ├── auth/           # Authentication pages
│   │   ├── chat/           # Chat UI
│   │   ├── setup/          # First-time setup flow
│   │   └── documentation/  # This page
│   ├── app.css            # Global styles & theme
│   └── app.html           # HTML shell and install metadata
├── tests/                  # unit/integration/e2e tests
├── migrations/             # Immutable D1 migration files
├── docs/                   # Extended project docs
└── wrangler.toml           # Cloudflare bindings/config

Deployment to Cloudflare Pages

1. Push your repository to GitHub.
2. In Cloudflare dashboard, open Pages and connect the repository.
3. Use build command bun run build.
4. Use output directory .svelte-kit/cloudflare.
5. Add D1, KV, and R2 bindings to the Pages project settings.
6. Add required environment variables and secrets.
7. Deploy and verify auth, setup flow, and database connectivity.

The local deploy script already uses wrangler pages deploy .svelte-kit/cloudflare.

Troubleshooting

• If setup API reports KV unavailable, create KV namespaces and update wrangler.toml binding IDs.
• If login fails after setup, confirm OAuth callback URL and ensure GitHub credentials are valid.
• If migrations fail, run bun run db:migrate:list and check migration numbering.
• If command palette entries are missing, verify AI provider status and authentication state.

Agent Readiness

This site publishes a machine-readable discovery layer so search crawlers and AI agents can find it, read it efficiently, and understand how to interact with it. Everything below is live without per-domain URL configuration. Placeholder Cloudflare bindings still make /api/health return 503 until project-owned D1/KV resources are configured.

• /robots.txt — crawl rules, explicit entries for AI crawlers (GPTBot, ClaudeBot, PerplexityBot and others), and Content Signals declaring how the content may be used.
• /sitemap.xml — every public page plus all published CMS content, regenerated on request so newly published items appear immediately.
• /.well-known/api-catalog — an RFC 9727 catalog of this deployment's APIs.
• /.well-known/agent-skills/index.json — short guides teaching an agent how to read content and contact the site, each with a SHA-256 digest.
• /auth.md — how agents authenticate (and what is not offered).
• /api/health — service health, used as the catalog's status link.

The catalog currently anchors these implemented endpoints: /api/contact-form-submissions, /api/health, /api/cms/types, /api/chat/models, and /api/chat/stream. Their catalog notes distinguish public, Turnstile-gated, and session-authenticated access.

Reading pages as Markdown

Any page can be fetched as Markdown instead of HTML by sending an Accept: text/markdown header. Browsers are unaffected — HTML remains the default. Responses include an x-markdown-tokens estimate so an agent can budget context before reading.

curl -H 'Accept: text/markdown' https://0b6os.com/

In-browser tools (WebMCP)

When opened by a WebMCP-capable agent, this site registers tools for searching content, listing pages, reading a page as Markdown, navigating, and switching theme. They are read-and-navigate only and restricted to this site's own origin. The page-reading tool enforces the public sitemap allowlist with browser credentials omitted, so an authenticated visitor cannot expose private/admin pages through WebMCP.

Content usage policy

The shipped default is fully permissive — search=yes, ai-input=yes, ai-train=yes — which matches 0B6OS's public open-source content. Change CONTENT_SIGNAL in src/lib/agent-discovery.ts before publishing any proprietary content; every robots.txt group picks the change up automatically.

DNS-based discovery (DNS-AID) is the one piece that must be added by hand, since DNS records live with your provider rather than in this repo. See docs/AGENT_READINESS.md for the exact records and the DNSSEC requirement.

References

• GitHub repository
• README
• Contributing Guide
• Cloudflare Setup
• Theme System
• Cloudflare Pages plus SvelteKit Guide

Contributing

Use TDD, keep changes small and reviewable, and run tests plus checks before opening a pull request.

• Write tests before implementation changes.
• Run bun run check, bun run test, and bun run test:coverage.
• Prefer Cloudflare-native services and minimal external dependencies.
• Do not edit past migration files; create a new one instead.