### Quick Start: Clone, Setup, and Verify Citadel

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

This snippet demonstrates the initial steps to clone the Citadel repository, navigate into the directory, install necessary tools and hooks, and then verify the setup by running tests, linting, and building the project.

```bash
# Clone and setup
git clone https://github.com/joestump/citadel.git
cd citadel
make install-tools
make install-hooks

# Verify setup
make test
make lint
make build
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Make command to install the necessary dependencies for building and running the project documentation.

```bash
make docs-install
```

--------------------------------

### Project Setup and Commands

Source: https://github.com/joestump/citadel/blob/main/CONTRIBUTING.md

Provides essential commands for setting up the project, running tests, and starting the daemon. These commands are typically executed using a build tool like Make.

```bash
make install
make test
make run
```

--------------------------------

### Run Development Documentation Server

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Make command to start a development server for the documentation with live reload. It watches for changes in `openspec/` and `regulations/`.

```bash
make docs-dev
```

--------------------------------

### Install Beads Server

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Provides installation instructions for the Beads server on macOS, Linux, FreeBSD, and Windows using various methods including Homebrew, a curl script, PowerShell, and building from source.

```bash
# macOS/Linux via Homebrew (recommended)
brew install steveyegge/beads/bd

# Quick install script (macOS/Linux/FreeBSD)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex

# From source (requires Go 1.22+)
git clone https://github.com/steveyegge/beads.git
cd beads
go build -o bd ./cmd/bd
```

--------------------------------

### Create and Start a LoopAgent

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/proactive-monitoring.md

Demonstrates how to instantiate and start a LoopAgent, which periodically executes a given function. Includes lifecycle management with graceful shutdown.

```go
agent := adk.NewLoopAgent(
    &adk.LoopAgentConfig{
        Name:     "my-monitor",
        Interval: 30 * time.Second,
    },
    func(ctx context.Context) error {
        // Check condition
        return nil
    },
)

agent.Start(ctx)
defers agent.Stop()
```

--------------------------------

### Verify Citadel Installation

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/installation.md

Verifies the successful installation of The Citadel by running the binary with the --version flag. This command should output the installed version of the Citadel CLI.

```bash
./bin/citadel --version
```

--------------------------------

### Create Bead Command-Line Example

Source: https://github.com/joestump/citadel/blob/main/AGENTS.md

An example command demonstrating how to create a new bead using the `/beads:create` command. It shows the usage of various flags to specify the title, type, priority, labels, description, acceptance criteria, and related notes for the bead.

```bash
/beads:create --title "🔒 Encrypt OAuth tokens at rest" \
  --type bug --priority 1 \
  --labels "cleanup,security,database,auth" \
  --description "OAuth tokens stored in plaintext. Violates AUTH-008.

## Acceptance Criteria
- System MUST encrypt tokens using AES-256-GCM
- System MUST auto-decrypt on query
- All tests MUST pass

## Notes
Files:
- `ent/schema/spotifyauth.go:21-23`
Related: spotter-ahw"
```

--------------------------------

### CI/CD Workflow File Example

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Reference to the GitHub Actions workflow file (`.github/workflows/ci.yml`) that outlines the CI/CD pipeline stages: Lint, Test, and Build.

```yaml
# .github/workflows/ci.yml
# 1. Lint - Runs golangci-lint
# 2. Test - Runs go test -race ./...
# 3. Build - Verifies compilation
```

--------------------------------

### TOML Boot Memory Configuration Example

Source: https://github.com/joestump/citadel/blob/main/openspec/specs/adk/design.md

Provides an example of how to configure per-agent boot memory settings in the citadel.toml file. This includes token budget, message and issue limits, and filtering options.

```toml
[[auditors]]
name = "auditor_general"

[auditors.boot_memory]
token_budget = 4000
message_limit = 20
issue_limit = 15
include_closed_issues = true
closed_lookback_days = 7
importance_filter = ["high", "urgent"]
issue_labels = ["federal-ticket", "compliance"]
```

--------------------------------

### Complete Citadel TOML Configuration Example

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/configuration.md

A comprehensive example of the citadel.toml file, illustrating all available configuration sections and their common settings. This serves as a template for setting up Citadel.

```toml
[citadel]
hostname = "citadel-control-01"
heartbeat_ms = 2000
log_level = "info"  # debug, info, warn, error

# MCP Server Configuration
# Servers can be command-based (stdio) or HTTP-based (streamable HTTP)

[mcp_servers.agent_mail]
type = "http"
url = "http://127.0.0.1:8765/mcp/"

[mcp_servers.beads]
command = "beads-mcp"
# Alternative: HTTP-based
# type = "http"
# url = "http://127.0.0.1:8766/mcp/"

# Citadel Paths
[paths]
regulations = "./regulations"
proposals = "./proposals"
archive = "./.citadel/archive"

# Git Provider (for PR-based voting)
[git_provider]
type = "github"  # or "gitlab"
token_env = "CITADEL_GIT_TOKEN"

[git_provider.github]
owner = "your-org"
repo = "citadel-regulations"

# ADK-Go Model Configuration
[model]
provider = "gemini"
model = "gemini-2.0-flash"
api_key_env = "GOOGLE_API_KEY"
temperature = 0.2

# Enforcement Settings
[enforcement]
ticket_cooldown_minutes = 60
notice_cooldown_minutes = 15
max_concurrent_tickets_per_agent = 5

# Legislative Settings
[legislative]
debate_opening_hours = 24
debate_rebuttal_hours = 48
debate_closing_hours = 12
voting_hours = 24
default_threshold = 0.5
constitutional_threshold = 0.66

```

--------------------------------

### Launch Citadel TUI (Recommended)

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/quickstart.md

Launches the Citadel Terminal User Interface (TUI) with an embedded daemon. This is the recommended starting method as it includes the daemon, TUI, and all auditor agents.

```bash
./bin/citadel
```

--------------------------------

### Install Development Tools with Make

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/installation.md

Installs essential development tools for the Citadel project using the Make build automation tool. This includes linters like golangci-lint and formatters like gofumpt.

```bash
make install-tools
```

--------------------------------

### Error Handling Examples (Bash)

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/gates/beads-gates.md

Command-line examples demonstrating error messages for various gate-related operations in Citadel. These include scenarios where a gate is not found, already resolved, or has an invalid await ID.

```bash
$ bd gate resolve nonexistent-id
Error: gate 'nonexistent-id' not found
```

```bash
$ bd gate resolve citadel-xyz
Error: gate 'citadel-xyz' is already resolved
```

```bash
$ bd gate check --type=gh:pr
Warning: Gate citadel-abc has invalid await_id 'invalid-pr'
```

--------------------------------

### TOML Model Configuration Example

Source: https://github.com/joestump/citadel/blob/main/openspec/specs/dynamic-model-switching/design.md

Example TOML configuration file for Citadel, defining default model settings and per-agent overrides. It specifies provider, model name, API key environment variable, and temperature for different agents.

```toml
# citadel.toml

[model]
provider = "gemini"
model = "gemini-2.0-flash"
api_key_env = "GOOGLE_API_KEY"
temperature = 0.2

# Per-agent model overrides (ADR-0003)
[model.agents.censor]
enabled = true
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"
temperature = 0.5

[model.agents.gatekeeper]
enabled = true
provider = "gemini"
model = "gemini-2.0-flash"
temperature = 0.1  # Lower temperature for deterministic merge decisions
```

--------------------------------

### Proposal File Example

Source: https://github.com/joestump/citadel/blob/main/REQUIREMENTS.md

An example of a proposal file format, likely used for suggesting changes or new regulations within the Citadel system. It includes fields for proposal name, proposer, date, status, problem statement, proposed regulation, rationale, and voting requirements.

```gherkin
# Example proposal file: proposals/example.proposal

Proposal: Proposal Name
  Proposed by: Agent Name
  Date: 2026-01-15
  Status: Under Debate

  Problem Statement:
    Description of the problem this proposal addresses.
    Can be multiple lines.

  Regulation: Proposed Regulation Name
    As the [Auditor Name]
    I want to [goal]
    So that [benefit]

    @proposed @severity:minor
    Scenario: Example scenario
      When [condition]
      Then issue Notice
        | field    | value          |
        | priority | advisory       |
        | reason   | [reason]       |

      Examples:
        | example_field |
        | value_1       |
        | value_2       |

  Rationale:
    Explanation of why this regulation is needed.
    Reference to supporting data or patterns.

  Vote: Requires majority (>50%) approval from all agents
```

--------------------------------

### Query Gate Metrics with jq

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/gates/examples.md

This bash snippet demonstrates how to use 'bd gate list --all --json' combined with 'jq' to analyze gate metrics. Examples include counting gates by type and calculating the average resolution time.

```bash
# Count gates by type
bd gate list --all --json | jq 'group_by(.await_type) | map({type: .[0].await_type, count: length})'

# Average resolution time
bd gate list --all --json | jq '[.[] | select(.resolved_at) | (.resolved_at | fromdate) - (.created_at | fromdate)] | add / length'
```

--------------------------------

### AI Model Configuration Examples (TOML)

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/configuration.md

Provides examples for configuring different AI model providers (Gemini, Anthropic, OpenAI) including API key and endpoint settings. It highlights the `api_key_env` requirement for certain providers.

```toml
[model]
provider = "gemini"
model = "gemini-2.0-flash"
api_key_env = "GOOGLE_API_KEY"
temperature = 0.2

```

```toml
[model]
provider = "anthropic"
model = "claude-3-5-sonnet-20241022"
api_key_env = "ANTHROPIC_API_KEY"
temperature = 0.2

```

```toml
[model]
provider = "openai"
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"
temperature = 0.2

```

```toml
[model]
provider = "openai"
model = "gpt-4o"
api_key_env = "AZURE_OPENAI_API_KEY"
base_url = "https://your-resource.openai.azure.com/openai/deployments/gpt-4o"
organization_id = "org-xxxxxxxx"  # Optional
temperature = 0.2

```

--------------------------------

### MCP Toolset Integration Example (Go)

Source: https://github.com/joestump/citadel/blob/main/openspec/project.md

Demonstrates how to integrate with MCP tools using ADK-Go. It shows setting up a command transport for 'beads-mcp' and initializing a toolset to be used with ADK-Go agents.

```go
// ADK-Go natively supports MCP tools
transport := &mcp.CommandTransport{
    Command: exec.CommandContext(ctx, "beads-mcp"),
}
toolset, _ := mcp.NewToolset(ctx, transport)

// Use toolset with ADK-Go agents
agent, _ := llmagent.New(llmagent.Config{
    Name: "auditor_general",
    Tools: toolset.Tools(),
})
```

--------------------------------

### Install and Run Agent Mail MCP Server

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

This snippet details the installation and running of the Agent Mail MCP server, a required component for The Citadel. It shows installation via pip and from source, followed by the command to start the server in HTTP mode for development.

```bash
# Using pip
pip install mcp-agent-mail

# Or from source
git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git
cd mcp_agent_mail
pip install -e .

# Running (HTTP mode)
mcp-agent-mail serve --host 127.0.0.1 --port 8765
```

--------------------------------

### Regulation File Example

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Example Gherkin syntax for defining a regulation in a `.regulation` file, including tags for auditor and enforcement, feature description, and a scenario with GIVEN, WHEN, THEN steps.

```gherkin
# openspec/regulations/my-regulation.regulation
@auditor:general
@enforcement:ticket
Feature: My Regulation

  Scenario: Violation condition
    GIVEN some precondition
    WHEN some action occurs
    THEN enforce the rule
```

--------------------------------

### Quick Start: Basic Logging with Citadel

Source: https://github.com/joestump/citadel/blob/main/pkg/logging/README.md

Demonstrates how to use the global logger for basic logging operations like Info, Debug, and Error. It also shows how to create component-specific loggers using the With method.

```go
import "github.com/joestump/citadel/pkg/logging"

// Use the global logger
logging.Info("server started", "port", 8080)
logging.Debug("processing request", "method", "GET")
logging.Error("failed to connect", "err", err)

// Create a component-specific logger
logger := logging.Default().With("component", "daemon")
logger.Info("daemon initialized")
```

--------------------------------

### List All Model Configurations (Go)

Source: https://github.com/joestump/citadel/blob/main/openspec/specs/dynamic-model-switching/design.md

Returns a list of all model configurations, including the system default and any per-agent overrides. Each entry provides details like agent ID, provider, model name, temperature, and active status.

```go
// ListModels returns all model configurations.
func (r *ModelRegistry) ListModels() []ModelInfo {
    r.mu.RLock()
    defer r.mu.RUnlock()

    var models []ModelInfo

    // Add default
    models = append(models, ModelInfo{
        AgentID:     "default",
        Provider:    r.defaultModel.Provider,
        Model:       r.defaultModel.Model,
        Temperature: r.defaultModel.Temperature,
        Active:      true,
        IsDefault:   true,
    })

    // Add per-agent configs
    for agentID, cfg := range r.agentModels {
        models = append(models, ModelInfo{
            AgentID:     agentID,
            Provider:    cfg.Provider,
            Model:       cfg.Model,
            Temperature: cfg.Temperature,
            Active:      cfg.Enabled,
            IsDefault:   false,
        })
    }

    return models
}
```

--------------------------------

### Start Work Workflow with Worktrees

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/worktrees.md

A step-by-step guide for starting development on an issue using Citadel's worktree system. It covers claiming an issue, creating an isolated worktree, navigating to it, and beginning coding on the new feature branch.

```bash
# 1. Claim the issue
bd update citadel-abc1 --status=in_progress

# 2. Create isolated worktree
citadel worktree create citadel-abc1

# 3. Navigate to it
cd ../citadel-abc1

# 4. You're now on feature/citadel-abc1 branch - start coding!
```

--------------------------------

### Configure Beads Server in citadel.toml

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Example TOML configuration for integrating the Beads server with Citadel, specifying the command and arguments to run.

```toml
[mcp_servers.beads]
command = "bd"
args = ["mcp"]
```

--------------------------------

### Serve Built Documentation

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Make command to serve the statically generated documentation files.

```bash
make docs-serve
```

--------------------------------

### Build Documentation for Production

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Make command to build the project documentation for production deployment.

```bash
make docs-build
```

--------------------------------

### Go Test Example with Mocks and Temp Directory

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

An example Go test function demonstrating best practices for Citadel's testing requirements. It utilizes `t.TempDir()` for file system operations and `httptest.NewServer` for mocking HTTP requests, ensuring tests are isolated and don't rely on external services.

```go
import (
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestMyFunction(t *testing.T) {
    // Use t.TempDir() for file operations
    tmpDir := t.TempDir()

    // Use httptest for HTTP mocking
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
    }))
    defer server.Close()

    // Test logic...
}
```

--------------------------------

### Clone Citadel Repository

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/installation.md

Clones the Citadel project repository from GitHub and navigates into the project directory. This is the first step in setting up the project locally.

```bash
git clone https://github.com/joestump/citadel.git
cd citadel
```

--------------------------------

### Connect TUI to Existing Citadel Daemon

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/quickstart.md

Demonstrates how to launch the TUI in one terminal while connecting to a pre-existing standalone Citadel daemon running in another. This allows for separation of the daemon and TUI processes.

```bash
# Start daemon in one terminal
./bin/citadel daemon start

# Launch TUI in another terminal (connects to existing daemon)
./bin/citadel
```

--------------------------------

### Beads MCP Server Configuration (TOML)

Source: https://github.com/joestump/citadel/blob/main/openspec/specs/beads/design.md

Configuration examples for the Beads MCP server using TOML format. It shows both command-based and HTTP-based setup options for integrating with The Citadel.

```toml
# citadel.toml

[mcp_servers.beads]
command = "beads-mcp"
# env.BEADS_WORKING_DIR = "/path/to/project"  # Optional

```

```toml
[mcp_servers.beads]
type = "http"
url = "http://127.0.0.1:8766/mcp/"

```

--------------------------------

### Linting and Formatting Citadel Code

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Commands for linting and automatically fixing code style issues in the Citadel project. 'make lint' runs the linter, and 'make lint-fix' attempts to resolve fixable issues. Pre-commit hooks can be installed to ensure code quality before commits.

```bash
# Run Linter
make lint

# Auto-fix Issues
make lint-fix

# Install Pre-commit Hooks
make install-hooks
```

--------------------------------

### Configure Pluggable Ticketing System in TOML

Source: https://github.com/joestump/citadel/blob/main/decisions/0006-pluggable-ticketing-system.md

Provides a TOML configuration example for the pluggable ticketing system. It demonstrates how to select a provider (e.g., 'beads', 'github', 'jira') and configure provider-specific settings such as command paths, repository details, API tokens, and label-to-priority mappings. This configuration enables dynamic selection and setup of different ticketing backends.

```toml
[ticketing]
provider = "beads"  # or "github", "jira", etc.

[ticketing.beads]
command = "beads-mcp"

[ticketing.github]
owner = "joestump"
repo = "citadel"
token_env = "GITHUB_TOKEN"
# Map GitHub labels to priority
priority_labels = { "P0" = 0, "P1" = 1, "P2" = 2, "P3" = 3, "P4" = 4 }

[ticketing.jira]
url = "https://company.atlassian.net"
project = "CITADEL"
token_env = "JIRA_API_TOKEN"
```

--------------------------------

### Install Pre-commit Hooks with Make

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/installation.md

Installs pre-commit hooks for the Citadel project using Make. These hooks help maintain code quality by running checks before each commit.

```bash
make install-hooks
```

--------------------------------

### Show Gate Details using Beads CLI

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/gates/beads-gates.md

Provides an example of how to display detailed information about a specific gate using the Beads CLI, including its status, type, creation time, description, and associated waiters.

```bash
bd gate show citadel-xyz
```

--------------------------------

### Configuration: Setting Up the Global Logger

Source: https://github.com/joestump/citadel/blob/main/pkg/logging/README.md

Shows how to configure the global logger at startup using a Config struct. This includes setting the log level, file path for output, a custom writer, and a callback function for TUI integration.

```go
import (
	"log"
	"os"
	"github.com/joestump/citadel/pkg/logging"
)

cfg := logging.Config{
    Level:    logging.InfoLevel,
    FilePath: "/var/log/citadel.log",  // Optional file output
    Writer:   os.Stderr,               // Custom writer
    Callback: func(entry logging.Entry) {
        // Send to TUI or metrics
    },
}

logger, err := logging.New(cfg)
if err != nil {
    log.Fatal(err)
}
logging.SetDefault(logger)
```

--------------------------------

### Run Beads Server

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/development.md

Instructions for initializing the Beads server in a project and upgrading to the latest version.

```bash
# Initialize in your project (one-time setup)
cd /path/to/your/project
bd init

# Upgrade to latest version
bd upgrade
```

--------------------------------

### Manage Citadel Standalone Daemon

Source: https://github.com/joestump/citadel/blob/main/docs-site/docs/usage/quickstart.md

Commands to manage the Citadel daemon as a background service. This includes starting, checking the status, and stopping the daemon independently of the TUI.

```bash
# Start the daemon
./bin/citadel daemon start

# Check status
./bin/citadel status

# Stop the daemon
./bin/citadel daemon stop
```