Getting Started

Quick Start

Reading (all org members)

1. Visit kb.ccmax.uk
2. Sign in with your GitHub account (must be an Eon-Labs org member)
3. Browse by category or use the search bar (Ctrl+K)

Editing (collaborators with write access)

# Clone the repo
git clone https://github.com/Eon-Labs/knowledgebase.git && cd knowledgebase

# Install dependencies
npm install

# Start local preview
npm run dev
# → Open http://localhost:4321

# Edit any page under src/content/docs/
# Pages are plain markdown with YAML frontmatter

# Deploy
mise run ship

Adding a New Page

Create a markdown file in the right category directory:

# Example: add a new engineering doc
cat > src/content/docs/engineering/my-new-doc.md << 'EOF'
---
title: My New Document
---

Your content here in standard markdown.
EOF

# Preview locally
npm run dev

# Ship when ready
mise run ship

Access Model

Role	Can view site?	Can view repo?	Can edit?	How to get access
Eon-Labs org member	Yes (GitHub login)	Yes (read)	No	Be added to Eon-Labs org
Repo collaborator	Yes	Yes	Yes (push)	Be invited to Eon-Labs/knowledgebase with Write role
External / public	No	No	No	Not accessible

• Site access is controlled by Cloudflare Zero Trust — GitHub OAuth validates org membership
• Repo access follows GitHub’s Team plan permissions — org admins manage roles
• Editing requires Write permission on the repo. Read-only members can view but not push.

Repository Structure

Eon-Labs/knowledgebase/
├── src/content/docs/          # All KB pages (markdown)
│   ├── index.mdx              # Landing page
│   ├── engineering/            # Engineering docs
│   │   ├── alphaforge/        # AlphaForge subsection
│   │   ├── data-platform/     # Data Platform subsection
│   │   ├── trading-systems/   # Trading Systems subsection
│   │   └── design-docs/       # ADRs, PRDs, RFCs
│   ├── research-books/        # Academic papers & books
│   ├── infrastructure-devops/ # Server, SSH, Git, Docker
│   ├── exchange-trading-ops/  # Binance, TradeStation, orders
│   ├── finance-accounting/    # SR&ED, CRA, tax, payroll
│   ├── grants-funding/        # Government programs, VCs
│   ├── legal-corporate/       # Agreements, compliance
│   ├── business-development/  # Pitch deck, go-to-market
│   ├── people-personnel/      # Project details, evals
│   ├── recruiting/            # Job postings, candidates
│   ├── administrative/        # Policies, handbooks
│   └── uncategorized/         # Pending categorization
├── scripts/                   # Build & maintenance scripts
│   ├── migrate_to_starlight.py
│   ├── link_integrity.py      # Zero-tolerance link checker
│   └── ...
├── astro.config.mjs           # Starlight configuration
├── .mise.toml                 # Task runner config
├── .mise/tasks/               # Build, check, ship tasks
├── CLAUDE.md                  # AI agent context (machine-readable)
├── KB-GUIDE.md                # This file (single source of truth)
└── .claude/skills/kb-ship/    # Deploy automation skill

Available Commands

All commands use mise as the task runner:

Command	What it does
mise run dev	Start local dev server at localhost:4321
mise run build	Build the static site to dist/
mise run ship	Build + deploy to production (kb.ccmax.uk)
mise run ship:preview	Build + deploy a preview URL for review
mise run check	Run Astro diagnostics
mise run check:full	Run all quality checks (lint, links, edit links)
mise run check:links-full	Complete link integrity check including external URLs
mise run count	Show page counts per category

Using with Claude Code

This repository is designed for Claude Code management. Claude reads CLAUDE.md for project context and uses the kb-ship skill for deployments.

# In Claude Code, just say:
"Add a page about X to the engineering section"
"Ship the KB"
"Check all links"
"How many pages do we have per category?"

Claude Code will:

1. Create/edit markdown files in src/content/docs/
2. Run quality checks via mise tasks
3. Build and deploy via the kb-ship skill
4. Validate all links before and after deploy

Technology Stack

Component	Tool	Purpose
Static site generator	Astro Starlight	Renders markdown to HTML with search, nav, dark mode
Search	Pagefind	Client-side full-text search (supports CJK)
Hosting	Cloudflare Pages	Static site hosting, CDN, preview deploys
Authentication	Cloudflare Zero Trust	GitHub OAuth, org-level access control
Task runner	mise	Build, check, ship commands
Link validation	starlight-links-validator + link_integrity.py	Zero-tolerance broken link detection
LLM access	starlight-llms-txt	Generates /llms.txt for AI ingestion

Content Guidelines

• Format: Standard markdown with YAML frontmatter (title: required)
• Images: Hosted on S3 (eonlabs-kb-assets.s3.us-east-1.amazonaws.com)
• Links: Use standard markdown links [text](/category/page/) — no wikilinks
• CJK: Chinese content is fully supported in search and rendering
• Frontmatter minimum: Just title: — everything else is optional

Conventions (what the build pipeline enforces)

The KB has a handful of conventions that several automated features depend on. If you break one, either the build fails loudly (good) or a widget silently drops your work (bad — so read this section).

Conventional Commit messages

Every commit should follow the Conventional Commits format: <type>(<scope>): <subject>. Valid types:

Type	When to use	Version bump	Appears in “Recently Updated”?
feat:	Adding new pages, new features, new content	minor	Yes
docs:	Documentation contributions, new reference material	patch	Yes
fix:	Bug fixes, typo corrections, broken-link repairs	patch	No
refactor:	Restructuring without changing behavior	patch	No
chore:	Build config, dependency bumps, release commits	patch	No
style:	Formatting-only changes	none	No
test:	Test-only changes	none	No

Why this matters:

1. semantic-release reads the commit history to decide the next version number. A commit without a recognized prefix is ignored → no release.
2. The <RecentlyUpdated> widget on the landing page filters to feat: / docs: commits. Mechanical cleanup (fix, chore, refactor) is correctly excluded so real contributions rise to the top. If you add real new content but use fix:, your page won’t appear in the widget.

If you’re adding a new page, use feat: or docs:. If you’re cleaning up an existing page, use fix: or chore:.

Single source of truth: src/config/kb-structure.mjs

Categories, subcategories, icons, labels, and the Starlight sidebar all derive from this one file. If you add a new category or new subcategory directory under src/content/docs/, you must also add an entry to kb-structure.mjs — otherwise the sidebar will silently hide your pages.

The check:kb-structure validator (part of mise run check:full, which runs before every ship) will fail the build if it detects drift. Example error:

validate_kb_structure: DRIFT DETECTED
  - Subcategory "engineering/new-thing/" exists on disk but is NOT declared
    in kb-structure.mjs under the engineering category.

Fix the drift by adding the subcategory to kb-structure.mjs and commit both the new content and the config update together.

Dynamic landing page widgets

• <CategoryGrid> — 8 category cards on the landing page, with live page counts. No hardcoding; reads getCollection('docs') at build time.
• <KBStats> — “N pages across M categories” total, also live.
• <CategoryToC> — each category landing page (e.g. /engineering/) auto-lists every page in its tree, grouped by subcategory. You never manually maintain a table of contents.
• <RecentlyUpdated limit={10}> — top 10 most recently authored pages (by feat:/docs: commit date). Runs git log --follow at build time.

All four components live in src/components/ and are consumed from src/content/docs/index.mdx and the category index.mdx files. Adding a new page = the page shows up in all four widgets automatically on the next ship.

Ship pipeline guarantees

mise run ship chains: check:full → build → wrangler deploy → semantic-release → mirror release to fork. Because ship now depends on check:full, you cannot ship broken content: markdownlint, edit-link validation, internal link integrity, Astro diagnostics, and kb-structure drift all run first. set -e halts the script on any failure before the deploy step runs, so a failed check never reaches production.