Skip to content
Lexicon

Quickstart

This guide walks through the happy path of setting up lexicon in a Rust project.

1. Initialize Lexicon

Section titled “1. Initialize Lexicon”

From your project root:

Terminal window
lexicon init

This launches an interactive workflow that asks for your project name, description, type (library/binary/workspace), and domain. It creates the .lexicon/ and specs/ directory structure with a manifest.toml, default gates, and a default scoring model.

Expected output:

Initializing lexicon
...
Lexicon initialized successfully

2. Start a Design Session

Section titled “2. Start a Design Session”
Terminal window
lexicon auth login    # one-time: authenticate with an AI provider
lexicon               # start a chat session

The chat session is the primary interface for building architecture artifacts. The AI guides you through:

  • Creating contracts (behavioral specifications for your components)
  • Defining gates (verification checks like fmt, clippy, tests)
  • Generating conformance tests, behavior scenarios, and edge cases
  • Scanning and baselining your public API
  • Compiling implementation prompts

Example interaction:

  Lexicon Design Session
  ────────────────────────────────────────────────────────────


you> I need an async key-value store with TTL


⠋ Thinking...
▸ Creating contract...
✓ Created contract: kv-store (specs/contracts/kv-store.toml)


Let me break down the key-value store requirements...

All artifacts are written to disk as they’re created. Sessions are saved automatically and can be resumed later.

3. Run Verification

Section titled “3. Run Verification”
Terminal window
lexicon verify

This runs all gates as subprocesses, computes the weighted score, checks coverage, detects API drift, and writes an audit record. Example output:

Running verification
────────────────────────
Gates
 ✓ fmt (42ms)
 ✓ clippy (1830ms)
 ✓ unit-tests (2105ms)
 ✓ doc-tests (890ms)


Score
 Total: 92.5% (PASS)
  correctness: 100% — fmt: passed in 42ms
  conformance-coverage: 50% — no gate configured
  ...
────────────────────────
All gates passed

Add --health for repo health checks:

Terminal window
lexicon verify --health

4. Launch the TUI

Section titled “4. Launch the TUI”
Terminal window
lexicon tui

Opens a terminal dashboard with tabs for Dashboard, Contracts, Gates, Score, and Help. Use Tab/arrow keys or number keys (1-5) to switch tabs, r to refresh, and q to quit.

Next Steps

Section titled “Next Steps”