Getting Started

Quick Start

Reading (all org members)

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

Editing (collaborators with write access)

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

# 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/kb 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/kb/
├── 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:

Create/edit markdown files in src/content/docs/
Run quality checks via mise tasks
Build and deploy via the kb-ship skill
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