# Quickstart

Build your first CEXAI artifact in under 5 minutes.

---

## Prerequisites

| Requirement | Minimum | Notes |
|-------------|---------|-------|
| Python | 3.10+ | Required for all CLI tools and SDK |
| git | 2.x+ | Artifacts are stored in git |
| LLM provider | At least one | Anthropic API key, OpenAI API key, Google AI key, or Ollama running locally |
| Claude Code CLI | Latest | Only needed if you want slash commands (`/build`, `/mission`, etc.) |

---

## Install

```bash
git clone https://github.com/GatoaoCubo/cex.git
cd cex
pip install -r requirements.txt
pip install -r requirements-llm.txt    # optional: LLM provider SDKs
pip install -e .                       # optional: install cex_sdk as a local package
```

Validate your setup:

```bash
python _tools/cex_setup_validator.py
```

This checks Python version, dependencies, directory structure, and API key availability.

---

## Boot Cost

CEXAI loads rules automatically when a Claude Code session starts. This is the "boot tax":

| What loads | Tokens | Purpose |
|------------|--------|---------|
| CLAUDE.md | ~3K | System map, pointers, commands |
| 8F reasoning rules | ~4K | The reasoning protocol |
| Orchestrator rules | ~5K | Routing, dispatch, lifecycle |
| GDP, ubiquitous language, ASCII rules | ~3K | Decision protocol, vocabulary, code safety |
| **Total** | **~15K** | Loaded once per session |

**Cost in context window:**
- 200K-context model: ~8% -- noticeable, but leaves 185K for work
- 1M-context model: ~1.5% -- negligible

The boot tax gives you the full 8F pipeline, GDP, and multi-nucleus routing for free. Every subsequent build benefits from the loaded rules without re-reading them.

If you use the CLI tools directly (no Claude Code session), there is no boot tax.

---

## Runtime Options

CEXAI runs on four providers. You can use one or mix them.

| Provider | Setup | Best for | Cost |
|----------|-------|----------|------|
| **Claude** (Anthropic) | `ANTHROPIC_API_KEY` in `.env` or Anthropic Max subscription | Production builds, deep reasoning | Paid |
| **GPT** (OpenAI) | `OPENAI_API_KEY` in `.env` | Alternative builds, embeddings | Paid |
| **Gemini** (Google) | `GOOGLE_API_KEY` in `.env` | Budget builds, free tier available | Free tier + paid |
| **Ollama** (local) | Install Ollama, pull a model | Zero-cost builds, privacy, fine-tuning | Free (your GPU) |

Routing is configured in `.cex/config/nucleus_models.yaml`. Each nucleus has a fallback chain:

```yaml
n03:
  model: opus-4-6
  context: 1000000
  fallback_chain: [claude, ollama]
```

Check provider health:

```bash
python _tools/cex_provider_discovery.py --status
python _tools/cex_quota_check.py --all
```

---

## Bootstrap Your Brand (optional)

CEXAI works without this, but all artifacts will be generic. Answer 6 questions to inject your brand identity into every output:

```bash
python _tools/cex_bootstrap.py
```

Or inside a Claude Code session:

```
/init
```

Questions asked: brand name, what you do, core values, personality (formal/casual), ideal customer, revenue model. Takes about 2 minutes. Saves hours of "make it sound more like us" revisions.

---

## Build Your First Artifact

### Option A: Claude Code (recommended)

Start a Claude Code session in the repo directory. CEX loads automatically. Type:

```
/build create a knowledge card about customer onboarding best practices
```

The 8F pipeline runs: resolves `kind=knowledge_card`, loads the builder's 12 ISOs, injects relevant knowledge cards, generates a structured markdown file with frontmatter, validates it against quality gates, saves it, and commits.

### Option B: Command line

```bash
python _tools/cex_8f_runner.py "customer onboarding best practices" \
    --kind knowledge_card --execute
```

### Option C: Python SDK

```python
from cex_sdk import CEXAgent

agent = CEXAgent(nucleus="n03", kind="knowledge_card")
result = agent.build("customer onboarding best practices")

print(result.score)      # quality score (0-10)
print(result.passed)     # True if score >= 8.0
print(result.artifact)   # the generated markdown
```

---

## What You Just Built

The output is a **knowledge card** -- a structured markdown file with:

```yaml
---
id: kc_customer_onboarding_best_practices
kind: knowledge_card
pillar: P01
title: "Customer Onboarding Best Practices"
version: 1.0.0
quality: null
tags: [onboarding, customer-success, best-practices]
---

## Summary
...

## Key Patterns
...

## Anti-Patterns
...
```

- **Frontmatter**: machine-readable metadata (kind, pillar, version, tags)
- **Body**: structured sections with domain knowledge
- **Quality**: validated by F7 GOVERN; `null` means not yet peer-reviewed

This artifact is now part of your knowledge base. Other builds can reference it. The retriever can find it. Future builds get smarter because it exists.

---

## Validate System Health

```bash
python _tools/cex_doctor.py              # builder integrity (300+ builders)
python _tools/cex_hooks.py validate-all  # frontmatter validation
python _tools/cex_system_test.py --quick # full system test (skip LLM calls)
```

---

## Next Steps

### Learn the architecture

```
/mentor what is a builder?
/mentor explain the 8F pipeline
/mentor what are the 12 pillars?
```

Or read [Concepts](concepts.md).

### Plan a multi-step mission

```
/plan customer support chatbot
```

This decomposes the goal into tasks, assigns nuclei, and identifies dependencies.

### Run a full mission

```
/mission build a customer support knowledge base with FAQ, onboarding flow, and escalation workflow
```

This runs the full lifecycle: plan, guide (ask you subjective questions), spec, grid (dispatch nuclei), and consolidate.

### Explore the tools

```bash
python _tools/cex_stats.py              # repo statistics
python _tools/cex_retriever.py --stats  # search index stats
python _tools/cex_coverage.py           # pillar coverage gaps
python _tools/cex_query.py "sales"      # find builders by keyword
```

### Evolve artifacts

```bash
python _tools/cex_evolve.py sweep --target 9.0    # improve artifacts below 9.0
python _tools/cex_score_python.py . --below 7.0   # find low-quality artifacts (no LLM cost)
```

---

## See Also

- [Concepts](concepts.md) -- 8F, 12P, GDP, kinds, nuclei in depth
- [CLI Reference](cli-reference.md) -- All 150+ tools with flags and examples
- [SDK Reference](sdk-reference.md) -- Python API for programmatic use
- [FAQ](faq.md) -- Common questions
- [Contributing](Contributing.md) -- How to add kinds, builders, and nuclei