NebulaKit Documentation

Start Here

This repository is the site at nebulakit.starspace.group. It runs on the NebulaKit platform but is not a template, and there is no customization workflow to complete — identity lives in src/lib/site.config.ts and nowhere else.

1. Clone the repository.
2. Install dependencies and run the app locally.
3. Apply database migrations locally.
4. Configure OAuth and owner access through the setup flow.
5. Run tests and coverage before shipping changes.

Quick Start

Then clone your repository, run the commands below, and open http://localhost:4278.

Bun is the recommended default for this repo. Switch to npm commands if your environment requires it.

								# 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

This starter already ships with the main product surfaces wired together. The fastest way to understand the repo is to think of it as a Cloudflare-first app shell with auth, theming, content management, and AI entry points already in place.

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. On a phone, tap the search icon in the navbar or choose "Search & commands" in the menu.
5. Use /chat for AI interactions, /profile for account settings, and /admin for operator tasks.
6. Use the theme toggle to verify light and dark presentation while you customize branding.

Drag and Drop

The widget board is a working feature of this site, not a demo you read about. Open the showcase to rearrange a live board; the layout you make is saved in your own browser.

Using it in your app

<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 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.

The Badge

The badge page hands out "Proudly built with NebulaKit" in six forms — Markdown for a README, HTML, a web component, and React, Svelte and Vue components — in three wordings and on either a dark or a light ground. Pick, preview, copy.

An app generated from the template already wears it: the footer carries BuiltWithNebulaKit.svelte, and showBuiltWithBadge: false in src/lib/site.config.ts removes it. NebulaKit is MIT-licensed, so the badge is a courtesy rather than a condition.

Endpoints

/badge.svg?variant=proudly|built|powered&theme=dark|light is the image a README embeds. /badge.js defines <nebulakit-badge>, which renders in a shadow root and follows the reader's own colour scheme. /badge-mark.svg?size=64 is the mark alone, for the cases the pill does not cover.

All three are served with Access-Control-Allow-Origin: *, because the badge is embedded cross-origin by definition. None of them loads a font, a stylesheet or a tracker: the mark is drawn inline and every colour is a literal, so the badge renders on a page that has never heard of this site. An unknown variant or theme renders the default badge rather than a 400 — a broken image in someone else's README tells them nothing.

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

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

• DB as D1 database binding (database name: nebulakit-site-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
npm run db:migrate:local

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

# List migration status
npm run db:migrate:list

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

Authentication and Setup Flow

Auth uses @auth/sveltekit with a setup-first workflow. The main routes are /setup, /auth/login, 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

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

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Check coverage
npm run test:coverage

# Run E2E tests
npm run test:e2e

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

Coverage guidance in repository docs is mixed: several files reference 90 percent, while AI assistant workflow instructions enforce 95 percent as a stricter floor. For new work, target 95 percent or higher to satisfy both interpretations safely.

Project Structure

NebulaKit/
├── .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 template
├── 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 npm 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 npm 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 and needs no configuration.

• /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.

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://nebulakit.starspace.group/

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, restricted to this site's own origin, and run with the visitor's existing permissions.

Content usage policy

The shipped default is fully permissive — search=yes, ai-input=yes, ai-train=yes — which suits an open template. If you build a site with proprietary content, change CONTENT_SIGNAL in src/lib/agent-discovery.ts before launching; 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
• 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 npm run check, npm run test, and npm run test:coverage.
• Prefer Cloudflare-native services and minimal external dependencies.
• Do not edit past migration files; create a new one instead.