### Shell Integration Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Shows how to use shell commands and `curl` to interact with the Scoop Codemap API, including starting the server and querying project context and working set.

```bash
#!/bin/bash

# Start server in background
codemap serve --port 9471 &
SERVER_PID=$!
trap "kill $SERVER_PID" EXIT

sleep 1  # Wait for server startup

# Query context
CONTEXT=$(curl -s http://127.0.0.1:9471/api/context)
LANGS=$(echo "$CONTEXT" | jq -r '.project.languages | join(", ")')
echo "Project languages: $LANGS"

# Check working set
WORKING=$(curl -s http://127.0.0.1:9471/api/working-set)
FILES=$(echo "$WORKING" | jq -r '.file_count')
echo "Files edited: $FILES"
```

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

### Get Session Start Output Bytes Budget

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Returns a bounded session-start hook output budget in bytes. Clamped to a safe range [1KB, MaxContextOutputBytes]. Defaults to 30KB if not set or negative, and clamps to the maximum if exceeded.

```go
func (c ProjectConfig) SessionStartOutputBytes() int
```

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

### Example Configuration

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

This JSON object shows a complete example of a configuration file, illustrating various settings for filtering, exclusion, depth, mode, budgets, routing strategies, and drift detection.

```json
{
  "only": ["rs", "sh", "sql", "toml", "yml"],
  "exclude": ["docs/reference", "docs/research"],
  "depth": 4,
  "mode": "auto",
  "budgets": {
    "session_start_bytes": 30000,
    "diff_bytes": 15000,
    "max_hubs": 8
  },
  "routing": {
    "retrieval": { 
      "strategy": "keyword", 
      "top_k": 3 
    },
    "subsystems": [
      {
        "id": "watching",
        "paths": ["watch/**"],
        "keywords": ["hook", "daemon", "events"],
        "docs": ["docs/HOOKS.md"],
        "agents": ["codemap-hook-triage"],
        "instructions": "# Hook Development\nThe watch system..."
      }
    ]
  },
  "drift": {
    "enabled": true,
    "recent_commits": 10,
    "require_docs_for": ["watching"]
  }
}
```

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

### Check if Config Needs Setup

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Illustrates how to assess the current configuration state using `config.AssessSetup`. It uses a switch statement to handle different setup states like 'Ready', 'Missing', or 'Boilerplate', and provides feedback on potential issues.

```go
assessment := config.AssessSetup(".")
switch assessment.State {
case config.SetupStateReady:
    fmt.Println("Config is ready")
case config.SetupStateMissing:
    fmt.Println("Run 'codemap setup' to initialize")
case config.SetupStateBoilerplate:
    fmt.Println("Config found but needs tuning")
default:
    fmt.Println("Config has issues:", assessment.Reasons)
}
```

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

### Start

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Starts the file system monitoring daemon if it is not already running. It creates a PID file and starts a background goroutine for event processing.

```APIDOC
## Start

### Description
Starts the daemon if not already running. This function is a no-op if the daemon is already active.

### Signature
```go
func (d *Daemon) Start() error
```

### Returns
- **`error`** - An error if the start process fails.

### Behavior
- No-op if daemon already running.
- Creates PID file at `.codemap/watch.pid`.
- Starts background goroutine for event processing.
```

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

### Setup Global Codemap Hooks

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Installs Codemap hooks globally into `~/.claude/settings.json`, affecting all projects.

```bash
codemap setup --global
```

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

### Increase Session Start Budget

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Configure a larger budget for session start in bytes. Increase this value if you are experiencing issues with large output being chopped due to budget exceeded.

```json
{
  "budgets": {
    "session_start_bytes": 50000
  }
}
```

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

### RenderHandoff Go Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/handoff.md

Shows how to render a human-readable text summary of a handoff artifact, with an option to include the full event timeline.

```Go
artifact, _ := handoff.LoadArtifact(".")
summary := handoff.RenderHandoff(artifact, false)
fmt.Println(summary)
// Output:
// # Handoff Summary (handoff.latest.json)
// ...
```

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

### Python Integration Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Demonstrates how to interact with the Scoop Codemap API using Python's requests library to get project context, matched skills, and skill details.

```python
import requests

API_URL = "http://127.0.0.1:9471/api"

# Get project context
response = requests.get(f"{API_URL}/context")
context = response.json()
print(f"Project: {context['project']['root']}")
print(f"Languages: {', '.join(context['project']['languages'])}")

# Get matched skills for a task
response = requests.get(f"{API_URL}/context", params={"intent": "refactor auth"})
context = response.json()
for skill in context.get("skills", []):
    print(f"- {skill['name']} (score: {skill['score']})")

# Get all refactor skills
response = requests.get(f"{API_URL}/skills", params={"category": "refactor"})
skills = response.json()["skills"]
for skill in skills:
    print(f"- {skill['name']}: {skill['description']}")

# Get skill details
response = requests.get(f"{API_URL}/skills/hub-safety")
print(response.text)  # Markdown content
```

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

### ProjectContext JSON Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

An example of how ProjectContext is represented in JSON format, showing project path, branch, file statistics, and top hub files.

```json
{
  "root": "/home/user/myproject",
  "branch": "feature/auth",
  "file_count": 245,
  "languages": ["go", "python", "bash"],
  "hub_count": 8,
  "top_hubs": ["pkg/handler/auth.go", "pkg/config/config.go", "main.go"]
}
```

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

### GetFileDetail Go Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/handoff.md

Demonstrates how to load an artifact and retrieve detailed context for a specific file, including its importers and whether it's a hub.

```Go
artifact, err := handoff.LoadArtifact(".")
detail, err := handoff.GetFileDetail(".", artifact, "pkg/config.go")
if err != nil {
    return err
}
fmt.Printf("Importers: %v\n", detail.Importers)
fmt.Printf("Is hub: %v\n", detail.IsHub)
```

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

### Check Scoop-Codemap Installation

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/errors.md

Command to verify the Scoop-Codemap installation, which can help diagnose issues with missing rule files.

```bash
codemap --version
```

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

### Assess Project Setup Configuration

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Inspects the .codemap/config.json file to determine if it requires initialization or tuning. Reports the assessment state and any specific reasons for attention.

```Go
assessment := config.AssessSetup(".")
if assessment.NeedsAttention() {
    fmt.Printf("State: %s\n", assessment.State)
    for _, reason := range assessment.Reasons {
        fmt.Printf("  - %s\n", reason)
    }
}
```

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

### HandoffRef JSON Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Demonstrates the JSON format for HandoffRef, specifying the artifact path, creation time, and metrics on file changes and risks.

```json
{
  "path": "/home/user/myproject/.codemap/handoff.latest.json",
  "generated_at": "2026-06-16T14:32:00Z",
  "changed_files": 8,
  "risk_files": 2
}
```

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

### Start Scoop Codemap Server

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Command to start the codemap server on a specified port. The server will listen on http://127.0.0.1:9471 by default.

```bash
codemap serve --port 9471
# Listens on http://127.0.0.1:9471
```

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

### Monitor and Display Filesystem Events

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Starts a daemon to watch for filesystem changes and prints events. Ensure the daemon is stopped using defer.

```go
daemon, err := watch.NewDaemon(".", false)
if err != nil {
    return err
}
defer daemon.Stop()

for {
    events := daemon.GetEvents(10)
    for _, e := range events {
        marker := "  "
        if e.IsHub {
            marker = "⚠️ "
        }
        fmt.Printf("%s[%s] %s %s\n", marker, e.Time.Format("15:04"), e.Op, e.Path)
    }
    time.Sleep(2 * time.Second)
}
```

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

### JavaScript/Node.js Integration Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Provides an example of integrating with the Scoop Codemap API using Node.js and the built-in `http` module to fetch project context information.

```javascript
const http = require('http');

async function getContext() {
    return new Promise((resolve, reject) => {
        http.get('http://127.0.0.1:9471/api/context', (res) => {
            let data = '';
            res.on('data', chunk => data += chunk);
            res.on('end', () => resolve(JSON.parse(data)));
        }).on('error', reject);
    });
}

async function main() {
    const context = await getContext();
    console.log(`Project: ${context.project.root}`);
    console.log(`Branch: ${context.project.branch}`);
    console.log(`Hub files: ${context.project.hub_count}`);
}

main();
```

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

### Setup Codemap Command

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/errors.md

The command to re-initialize or set up the codemap configuration. This can be used to regenerate corrupted state or configuration files.

```bash
codemap setup
```

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

### Start codemap server and check health

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Starts the codemap HTTP server and then sends a health check request to verify it's running.

```bash
codemap serve --port 9471
curl http://127.0.0.1:9471/api/health
```

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

### SkillRef JSON Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Example JSON representation of a SkillRef, showing the skill name, its score, and the justification for its relevance.

```json
{
  "name": "hub-safety",
  "score": 85,
  "reason": "Editing hub file cmd/hooks.go (12 importers)"
}
```

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

### Session Start Hook

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/README.md

Initiates a session by reading daemon state and outputting hub summary and file count context for Claude Code.

```bash
codemap hook session-start
```

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

### Shell Integration Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Demonstrates how to capture the compact context output into a shell variable and parse specific fields using `jq`. This allows for programmatic use of codemap context in shell scripts.

```bash
CONTEXT=$(codemap context --compact)
INTENT=$(echo "$CONTEXT" | jq -r '.intent.task')
HUBS=$(echo "$CONTEXT" | jq -r '.project.top_hubs | join(", ")')

echo "Task: $INTENT"
echo "Hubs at risk: $HUBS"
```

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

### Subcommand Usage Examples

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Demonstrates different ways to use the `codemap context` subcommand, including full JSON output, with intent classification, and with compact output.

```bash
codemap context                       # Full JSON envelope
```

```bash
codemap context --for "refactor auth" # With intent classification
```

```bash
codemap context --compact             # Minimal output
```

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

### Test Codemap Configuration with CLI Override

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Tests the configuration by applying overrides via command-line flags before saving. This example limits the output to Go files and shows the first 20 lines.

```bash
codemap --debug --only go . | head -20
```

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

### Build and Save Fresh Handoff

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/handoff.md

Builds a new handoff artifact from the current directory and saves it. Useful for initial setup or when no previous artifact exists.

```go
opts := handoff.BuildOptions{
    BaseRef: "main",
    Since:   6 * time.Hour,
}
artifact, err := handoff.BuildHandoff(".", opts)
if err != nil {
    return err
}
if err := handoff.SaveArtifact(".", artifact); err != nil {
    return err
}

// Hand off to agent
summary := handoff.RenderHandoff(artifact, false)
fmt.Println(summary)
```

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

### Marshal Project to JSON for Piping

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/render.md

Outputs project data as JSON, suitable for piping to other command-line tools like jq. This pattern is identical to the first JSON example but emphasizes its use in a pipeline.

```go
project := loadProject(".")
data, _ := json.MarshalIndent(project, "", "  ")
fmt.Println(string(data))
```

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

### Example of CLI Flag Overriding Config

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/README.md

Demonstrates how a CLI flag can override a corresponding setting in the project's configuration file.

```text
Example: `codemap --only go . ` overrides config.json "only" field.
```

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

### WorkingFileContext JSON Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Illustrates the JSON structure for a WorkingFileContext, detailing a file's path, editing activity, line count changes, and its hub status.

```json
{
  "path": "cmd/hooks.go",
  "edit_count": 5,
  "net_delta": 127,
  "is_hub": true
}
```

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

### ValidateArtifact Go Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/handoff.md

Illustrates how to validate the structure and integrity of a handoff artifact before processing it. Logs an error if the artifact is invalid.

```Go
artifact, _ := handoff.LoadArtifact(".")
if err := handoff.ValidateArtifact(artifact); err != nil {
    fmt.Fprintf(os.Stderr, "Invalid artifact: %v\n", err)
}
```

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

### Get full project context

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Retrieves the complete context envelope for the current project. Use the 'compact' parameter for a minimal response.

```json
{
  "version": 1,
  "generated_at": "2026-06-16T14:32:00Z",
  "project": {
    "root": "/home/user/myproject",
    "branch": "feature/auth",
    "file_count": 245,
    "languages": ["go", "python"],
    "hub_count": 8,
    "top_hubs": ["pkg/handler/auth.go"]
  },
  "intent": null,
  "working_set": null,
  "skills": [],
  "handoff": null,
  "budget": {
    "total_bytes": 2347,
    "compact": false
  }
}
```

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

### Enable Dependency Flow Mode

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Use the `--deps` flag to enable dependency flow mode, which requires ast-grep to be installed.

```bash
codemap --deps .
```

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

### AnimateSkyline Example Usage

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/render.md

Demonstrates how to use the AnimateSkyline function to generate and display animation frames. The animation runs asynchronously and the channel should be closed to stop it.

```go
frames := render.AnimateSkyline(project, 10)
for frame := range frames {
    fmt.Print(frame)
    time.Sleep(100 * time.Millisecond)
}
```

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

### Codemap Configuration JSON

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/INDEX.md

Example JSON configuration for codemap, specifying included file extensions and the analysis depth.

```json
{
  "only": ["go", "ts"],
  "depth": 4
}
```

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

### Get Default Routing Strategy

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Returns a supported routing strategy for prompt-submit hints, defaulting to 'keyword'. It returns 'keyword' for any invalid values.

```go
func (c ProjectConfig) RoutingStrategyOrDefault() string
```

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

### Redirect Codemap Server Logs

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Command to start the codemap server and redirect its logs to a file. Server logs are sent to stderr by default.

```bash
codemap serve --port 9471 2> codemap-server.log
```

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

### LooksBoilerplate

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Reports whether the configuration resembles a bare bootstrap setup, primarily containing auto-detected extensions. This helps identify configurations that might need further tuning.

```APIDOC
## LooksBoilerplate

### Description
Reports whether the config resembles a bare bootstrap (auto-detected extensions only).

### Method
```go
func (c ProjectConfig) LooksBoilerplate() bool
```

### Returns
- `bool` — True if config only contains extension filters and needs tuning.

### Behavior
- Returns false if excludes, budgets, or policies are set.
- Intended to prompt users to add project-specific excludes.
- Helps distinguish "initial auto-config" from "configured project".
```

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

### ScanForDeps: Analyze Project Dependencies

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/scanner.md

Use ScanForDeps to perform batched, multi-language dependency analysis on a project root. It requires ast-grep to be installed and in the system's PATH. The function returns per-file import and function analysis, or an error if ast-grep is unavailable.

```go
analyses, err := scanner.ScanForDeps(".")
if err != nil {
    return err
}
for _, a := range analyses {
    fmt.Printf("%s (%s):\n", a.Path, a.Language)
    fmt.Printf("  Functions: %v\n", a.Functions)
    fmt.Printf("  Imports: %v\n", a.Imports)
}
```

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

### Load and Use Config Defaults

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Demonstrates how to load a configuration from the current directory and access default values for session budgets and display limits. It also shows how to retrieve the operational mode, defaulting to 'auto' if not specified.

```go
cfg := config.Load(".")

// Get bounded budgets
sessionBytes := cfg.SessionStartOutputBytes()
diffBytes := cfg.DiffOutputBytes()
maxHubs := cfg.HubDisplayLimit()

// Get CLI-friendly mode
mode := cfg.ModeOrDefault()
```

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

### Get Diff Output Bytes Budget

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Returns a bounded diff hook output budget in bytes. Clamped to a safe range [1KB, MaxContextOutputBytes]. Defaults to 15KB if not set or negative, and clamps to the maximum if exceeded.

```go
func (c ProjectConfig) DiffOutputBytes() int
```

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

### Get Config File Path

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Returns the full path to the .codemap/config.json file for a given project root directory. This is a helper function to construct the expected file location.

```Go
path := config.ConfigPath(".")
// Returns: "./.codemap/config.json"
```

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

### Get Hub Display Limit

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Returns the maximum number of hubs to display during session start. Clamped to the range [1, 100]. Defaults to 10 if not set or negative, and clamps to 100 if exceeded.

```go
func (c ProjectConfig) HubDisplayLimit() int
```

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

### AssessSetup

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Inspects .codemap/config.json and reports whether it needs initialization or tuning.

```APIDOC
## AssessSetup

### Description
Inspects .codemap/config.json and reports whether it needs initialization or tuning.

### Function Signature
```go
func AssessSetup(root string) SetupAssessment
```

### Parameters
#### Path Parameters
- **root** (string) - Required - Project root

### Returns
- **SetupAssessment** — Assessment with state and reasons.

### Assessment states:
- `SetupStateReady`: Config is properly configured
- `SetupStateMissing`: No .codemap/config.json file exists
- `SetupStateMalformed`: File exists but contains invalid JSON
- `SetupStateEmpty`: File exists but is blank or contains empty JSON object
- `SetupStateBoilerplate`: Config only contains auto-detected extensions and needs tuning

### Example
```go
assessment := config.AssessSetup(".")
if assessment.NeedsAttention() {
    fmt.Printf("State: %s\n", assessment.State)
    for _, reason := range assessment.Reasons {
        fmt.Printf("  - %s\n", reason)
    }
}
```
```

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

### Configure Hook Timeouts and Silence

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Configure hook execution timeouts and whether to run them silently in `.claude/settings.local.json`. This example sets a 10-second timeout for 'session-start' and a 5-second timeout for 'post-edit'.

```json
{
  "hooks": {
    "session-start": {
      "timeout": "10s",
      "silent": false
    },
    "post-edit": {
      "timeout": "5s",
      "silent": false
    }
  }
}
```

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

### Initialize Codemap Config from Scratch

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Explicitly initializes the configuration, creating `.codemap/config.json`.

```bash
codemap config init
```

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

### Create and Use a New Watch Daemon

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Initializes a new file system monitoring daemon and retrieves recent events. Ensure to stop the daemon when done using defer.

```Go
daemon, err := watch.NewDaemon(".", false)
if err != nil {
    return err
}
defer daemon.Stop()

events := daemon.GetEvents(10)
for _, e := range events {
    fmt.Printf("[%s] %s %s\n", e.Time.Format("15:04"), e.Op, e.Path)
}
```

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

### SessionStartOutputBytes

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Retrieves a bounded session-start hook output budget in bytes. This method ensures the output is within a safe range, defaulting to 30KB if not specified or if the specified value exceeds the maximum context output bytes.

```APIDOC
## SessionStartOutputBytes

### Description
Returns a bounded session-start hook output budget (bytes). This method clamps the output to a safe range of [1KB, MaxContextOutputBytes].

### Method
```go
func (c ProjectConfig) SessionStartOutputBytes() int
```

### Returns
- `int` — Clamped to safe range [1KB, MaxContextOutputBytes].

### Behavior
- If `Budgets.SessionStartBytes` is 0 or negative, returns default (30KB).
- If set value exceeds MaxContextOutputBytes, clamps to max.
- Prevents context blowup in session-start hooks.
```

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

### GET /api/health

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Health check endpoint to monitor server availability.

```APIDOC
## GET /api/health

### Description
Health check endpoint to monitor server availability.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200 OK)
- **status** (string) - Indicates the server is operational.

### Response Example
```json
{
  "status": "ok"
}
```
```

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

### GET /api/skills/<name>

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/INDEX.md

Retrieves detailed information about a specific skill.

```APIDOC
## GET /api/skills/<name>

### Description
Retrieves detailed information about a specific skill.

### Method
GET

### Endpoint
/api/skills/<name>

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the skill to retrieve details for.

#### Query Parameters
- **?language** (string) - Optional - Filter skills by language
- **?category** (string) - Optional - Filter skills by category

### Response
#### Success Response (200)
- **skillDetails** (object) - Detailed information about the specified skill.
```

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

### CLI Entry Point (main.go)

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/README.md

The main function serves as the entry point for the command-line interface. It handles global flag parsing and routes execution to various subcommands or operational modes.

```go
func main() {
    // Parses global flags (--depth, --only, --exclude, --deps, etc.)
    // Routes to subcommands (setup, config, hook, mcp, context, serve, handoff, skill)
    // Or runs tree/skyline/diff/deps mode
}
```

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

### GET /api/context

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/INDEX.md

Retrieves the full context envelope for the current project.

```APIDOC
## GET /api/context

### Description
Retrieves the full context envelope for the current project.

### Method
GET

### Endpoint
/api/context

### Parameters
#### Query Parameters
- **?intent** (string) - Optional - Pre-classify intent
- **?compact** (boolean) - Optional - Minimal output
- **?language** (string) - Optional - Filter skills
- **?category** (string) - Optional - Filter skills

### Response
#### Success Response (200)
- **context** (object) - The full context envelope.
```

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

### GET /api/health

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/INDEX.md

Performs a health check on the Scoop Codemap service.

```APIDOC
## GET /api/health

### Description
Health check for the Scoop Codemap service.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service.
```

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

### GET /api/skills

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/INDEX.md

Lists all available skills within the Scoop Codemap service.

```APIDOC
## GET /api/skills

### Description
Lists all available skills within the Scoop Codemap service.

### Method
GET

### Endpoint
/api/skills

### Parameters
#### Query Parameters
- **?language** (string) - Optional - Filter skills by language
- **?category** (string) - Optional - Filter skills by category

### Response
#### Success Response (200)
- **skills** (array) - A list of available skills.
```

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

### Override Config with CLI Flags

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Shows how to load a configuration and then conditionally apply settings based on CLI flags. If a flag is provided, its value is used; otherwise, the value from the configuration file is used.

```go
cfg := config.Load(".")

// CLI flags take precedence
var only []string
if flagOnly != "" {
    only = parseOnly(flagOnly)
} else if len(cfg.Only) > 0 {
    only = cfg.Only
}
```

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

### GET /api/skills

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Lists all available skills with their metadata, with options to filter by language or category.

```APIDOC
## GET /api/skills

### Description
Lists all available skills with their metadata. This endpoint allows filtering skills by programming language and category, useful for finding relevant tools for specific tasks.

### Method
GET

### Endpoint
/api/skills

### Parameters
#### Query Parameters
- **language** (string) - Optional. Filters skills by programming language (e.g., `go`, `python`).
- **category** (string) - Optional. Filters skills by category (e.g., `refactor`, `test`).

### Response
#### Success Response (200 OK)
- **skills** (array) - A list of skill objects.
  - **name** (string) - The unique name of the skill.
  - **description** (string) - A brief description of the skill's purpose.
  - **keywords** (array of strings) - Associated keywords for the skill.
  - **languages** (array of strings) - Programming languages supported by the skill.
  - **category** (string) - The category the skill belongs to.
  - **activation** (string) - Conditions or triggers for skill activation.

### Request Example
```bash
curl 'http://127.0.0.1:9471/api/skills?language=go&category=refactor'
```

### Response Example
```json
{
  "skills": [
    {
      "name": "hub-safety",
      "description": "Avoid breaking hub files",
      "keywords": ["hub", "refactoring", "impact"],
      "languages": ["go", "python", "typescript"],
      "category": "refactor",
      "activation": "Editing files with 3+ importers"
    },
    {
      "name": "refactor",
      "description": "Safely restructure code",
      "keywords": ["refactoring", "moving", "renaming"],
      "languages": [],
      "category": "refactor",
      "activation": "When prompt mentions 'refactor' or 'restructure'"
    }
  ]
}
```
```

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

### Render Project Tree with Color

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/render.md

Renders the project tree. Use RenderColoredTree for colored output in a TTY environment, otherwise use RenderTree for plain text.

```go
project := loadProject(".")
if isTTY {
    fmt.Println(render.RenderColoredTree(project))
} else {
    fmt.Println(render.RenderTree(project))
}
```

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

### Get server health status

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

This endpoint is used to monitor the availability of the codemap server.

```json
{
  "status": "ok"
}
```

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

### GET /api/working-set

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/INDEX.md

Retrieves information about the files in the current session's working set.

```APIDOC
## GET /api/working-set

### Description
Retrieves information about the files in the current session's working set.

### Method
GET

### Endpoint
/api/working-set

### Parameters
#### Query Parameters
- **?compact** (boolean) - Optional - Minimal output

### Response
#### Success Response (200)
- **workingSet** (array) - A list of files in the current working set.
```

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

### Get specific skill details

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Retrieves the full content and metadata for a single, specified skill by its name.

```markdown
# Hub Safety

When editing a "hub" file (3+ importers), be aware of cascading impact.

## Risk Assessment

- **High risk**: Hub handles critical infrastructure (config, logging, auth)
- **Medium risk**: Hub is utility library used widely but not infrastructure
- **Low risk**: Hub is recent addition with minimal dependents

## Techniques

1. **Before editing**: List importers
   ```bash
   codemap --importers pkg/config.go
   ```

2. **Test coverage**: Ensure importers have tests
   ...

```

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

### Get Working Set Size

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Returns the total number of files currently tracked within the working set.

```go
func (ws *WorkingSet) Size() int
```

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

### Build and Query File Dependency Graph

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/scanner.md

Builds a file dependency graph for a project and provides methods to query for hub files (files with many importers) and specific import relationships.

```go
graph, err := scanner.BuildFileGraph(".")
if err != nil {
    return err
}

// Find hub files (3+ importers)
hubs := graph.HubFiles()

// Check impact of a specific file
importers := graph.Importers["pkg/config.go"]
imports := graph.Imports["pkg/config.go"]
```

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

### Running Go Tests

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/README.md

Tests are written using Go's standard `testing` package and are located in files with the `_test.go` suffix. Run all tests within the project using the `go test ./...` command.

```bash
go test ./...
```

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

### GET /api/working-set

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Retrieves a summary of the current session's active files, including edit counts and hub status.

```APIDOC
## GET /api/working-set

### Description
Retrieves a summary of the current session's active files. This endpoint is useful for understanding the scope of current work or providing context-aware information to users.

### Method
GET

### Endpoint
/api/working-set

### Response
#### Success Response (200 OK)
- **file_count** (integer) - The total number of files in the working set.
- **hub_count** (integer) - The number of hub files within the working set.
- **top_files** (array) - A list of the most active files.
  - **path** (string) - The path to the file.
  - **edit_count** (integer) - The number of edits made to the file.
  - **net_delta** (integer) - The net change in lines for the file.
  - **is_hub** (boolean) - Indicates if the file is a hub file.

### Response Example
```json
{
  "file_count": 3,
  "hub_count": 1,
  "top_files": [
    {
      "path": "cmd/hooks.go",
      "edit_count": 5,
      "net_delta": 127,
      "is_hub": true
    },
    {
      "path": "main.go",
      "edit_count": 2,
      "net_delta": 42,
      "is_hub": false
    }
  ]
}
```
```

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

### Enable City Skyline Visualization

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Use the `--skyline` flag to generate a city skyline visualization of the project structure.

```bash
codemap --skyline
```

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

### GET /api/context

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Retrieves the full context envelope for the current project, optionally including intent classification or a compact output.

```APIDOC
## GET /api/context

### Description
Retrieves the full context envelope for the current project. This endpoint can be used to get detailed project information, including version, generation time, project structure, and optionally classified intent, skills, and working set details. It also supports a compact output for token-constrained environments.

### Method
GET

### Endpoint
/api/context

### Parameters
#### Query Parameters
- **intent** (string) - Optional. A task description for intent classification.
- **compact** (boolean) - Optional. Defaults to `false`. If `true`, returns a minimal envelope.

### Response
#### Success Response (200 OK)
- **version** (integer) - The version of the context envelope.
- **generated_at** (string) - The timestamp when the context was generated.
- **project** (object) - Information about the project.
  - **root** (string) - The root directory of the project.
  - **branch** (string) - The current branch of the project.
  - **file_count** (integer) - The total number of files in the project.
  - **languages** (array of strings) - List of programming languages used in the project.
  - **hub_count** (integer) - The number of hub files.
  - **top_hubs** (array of strings) - Paths to the top hub files.
- **intent** (string or null) - The classified intent of the task, if provided and classified.
- **working_set** (object or null) - Details about the current working set.
- **skills** (array) - List of matched skills.
- **handoff** (object or null) - Handoff information.
- **budget** (object) - Budget details.
  - **total_bytes** (integer) - Total bytes allocated.
  - **compact** (boolean) - Whether compact mode is enabled.

### Request Example
```bash
curl 'http://127.0.0.1:9471/api/context?intent=refactor+auth'
```

### Response Example
```json
{
  "version": 1,
  "generated_at": "2026-06-16T14:32:00Z",
  "project": {
    "root": "/home/user/myproject",
    "branch": "feature/auth",
    "file_count": 245,
    "languages": ["go", "python"],
    "hub_count": 8,
    "top_hubs": ["pkg/handler/auth.go"]
  },
  "intent": null,
  "working_set": null,
  "skills": [],
  "handoff": null,
  "budget": {
    "total_bytes": 2347,
    "compact": false
  }
}
```
```

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

### Basic Context Query

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Retrieves basic project context information. This is the default behavior when no flags are specified.

```bash
codemap context
```

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

### Request compact project context

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Fetches a minimal version of the project context by setting the 'compact' query parameter to true.

```bash
curl 'http://127.0.0.1:9471/api/context?compact=true'
```

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

### Render Project as File Tree

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/render.md

Renders a project's file structure as a hierarchical tree, including file counts, sizes, and extensions. Respects a depth limit and is color-coded for terminals.

```go
func RenderTree(project *scanner.Project) string
```

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

### Render Project as Skyline Visualization

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/render.md

Visualizes file sizes as building heights in a city skyline, grouping files by directory. Supports ASCII art animation for terminals when enabled.

```go
func RenderSkyline(project *scanner.Project, animate bool) string
```

```text
 ██                  ██
 ██   ██      ██  ██ ██
 ██ ██ ██ ██  ██  ██ ██
 ██ ██ ██ ██  ██  ██ ██
 ██ ██ ██ ██  ██  ██ ██
```

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

### Configuration Priority Order

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/README.md

Configuration settings are loaded in a specific priority order, with CLI flags taking precedence over project configuration files and default constants.

```text
1. CLI flags (highest priority)
2. .codemap/config.json (project config)
3. Default constants (lowest priority)
```

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

### Example Git Not a Repository Error

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/errors.md

Shows the error message when the project root is not initialized as a Git repository. This error can be triggered by any GitDiff* function.

```bash
fatal: not a git repository (or any of the parent directories): .git
```

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

### Create GitIgnoreCache

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/scanner.md

Initializes a cache for handling nested .gitignore files. It lazily loads .gitignore rules and supports negation patterns.

```go
cache := scanner.NewGitIgnoreCache(".")
cache.EnsureDir("src/components")
if !cache.ShouldIgnore("src/components/excluded.ts") {
    // Process file
}
```

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

### Render Project as Colored File Tree

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/render.md

Similar to RenderTree, but includes ANSI color codes for terminal output. Directories are blue, source files green, config/doc files yellow, and binary/media files dimmed.

```go
func RenderColoredTree(project *scanner.Project) string
```

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

### Get Hub File Count

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Returns the count of hub files that are currently being edited within the working set. Alerts if any hubs are being edited.

```go
func (ws *WorkingSet) HubCount() int
```

```go
hubsEdited := ws.HubCount()
if hubsEdited > 0 {
    fmt.Printf("⚠️  %d hubs are being edited\n", hubsEdited)
}
```

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

### Create New Working Set

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Initializes an empty WorkingSet for a new session. The returned set includes the current timestamp.

```go
func NewWorkingSet() *WorkingSet
```

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

### Get current working set files

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/endpoints.md

Retrieves information about the files currently active in the session, including edit counts and hub status.

```json
{
  "file_count": 3,
  "hub_count": 1,
  "top_files": [
    {
      "path": "cmd/hooks.go",
      "edit_count": 5,
      "net_delta": 127,
      "is_hub": true
    },
    {
      "path": "main.go",
      "edit_count": 2,
      "net_delta": 42,
      "is_hub": false
    }
  ]
}
```

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

### BudgetInfo Go Struct

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Contains metrics about the size of the context envelope, including total bytes and whether compact output was used.

```go
type BudgetInfo struct {
    TotalBytes int
    Compact    bool
}
```

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

### Load Project Configuration

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Reads the .codemap/config.json file from the specified project root. Returns a zero-value ProjectConfig if the file is missing or malformed. Logs warnings to stderr for malformed JSON but never throws an error.

```Go
cfg := config.Load(".")
fmt.Printf("Only extensions: %v\n", cfg.Only)
fmt.Printf("Max depth: %d\n", cfg.Depth)
```

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

### Configure Budgets for Claude Code Hooks

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Set output size constraints for Claude Code hooks, including session start, diff, and maximum hubs.

```json
{
  "budgets": {
    "session_start_bytes": 30000,
    "diff_bytes": 15000,
    "max_hubs": 8
  }
}
```

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

### Enable Animated Skyline Visualization

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Use the `--animate` flag in conjunction with `--skyline` to create an animated city skyline visualization.

```bash
codemap --skyline --animate
```

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

### Check and Stop Existing Daemon Before Creation

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/errors.md

Before creating a new daemon, check if one is already running for the given root. If it is, stop the existing daemon to prevent a PID file conflict.

```go
if watch.IsRunning(root) {
    watch.Stop(root)
}
daemon, err := watch.NewDaemon(root, false)
```

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

### ContextEnvelope Go Struct

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Defines the complete context package for AI tool consumption. It includes versioning, generation timestamp, project details, task intent, working set, matched skills, handoff references, and budget information.

```go
type ContextEnvelope struct {
    Version     int
    GeneratedAt time.Time
    Project     ProjectContext
    Intent      *TaskIntent
    WorkingSet  *WorkingSetContext
    Skills      []SkillRef
    Handoff     *HandoffRef
    Budget      BudgetInfo
}
```

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

### Get Default Mode

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/config.md

Returns a valid hook orchestration mode, defaulting to 'auto'. It handles case-insensitivity and returns 'auto' for invalid or missing mode values.

```go
func (c ProjectConfig) ModeOrDefault() string
```

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

### Enable Live File Watcher

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/configuration.md

Use the `--watch` flag to enable a live file watcher daemon that automatically re-analyzes the project on file changes. This feature is experimental.

```bash
codemap --watch
```

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

### Read Cached State in Hooks

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Reads the latest cached state without starting a daemon, useful for hook integrations. Checks if state is available before accessing its properties.

```go
// In a hook, don't start daemon; just read cached state
state := watch.ReadState(".")
if state != nil {
    fmt.Println("Hub files:", state.Hubs)
    fmt.Printf("Recent changes: %d\n", len(state.RecentEvents))
}
```

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

### NewDaemon

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Creates a new file system monitoring daemon. It starts watching for file changes, scans dependencies, maintains an event buffer, and updates the working set.

```APIDOC
## NewDaemon

### Description
Creates a new file system monitoring daemon that monitors file changes and maintains dependency-aware event history.

### Signature
```go
func NewDaemon(root string, verbose bool) (*Daemon, error)
```

### Parameters
#### Path Parameters
- **root** (string) - Required - Project root directory
- **verbose** (bool) - Optional - Enable debug logging

### Returns
- **`*Daemon`** - A pointer to the running daemon.
- **`error`** - An error if the watch setup fails.

### Behavior
- Starts watching for file changes.
- Scans dependencies (if ast-grep available).
- Maintains an event buffer with the recent 50 changes.
- Updates the working set with each file modification.
- Periodically saves state to `.codemap/watch.state.json`.

### Throws
- If the root directory does not exist.
- If the filesystem watcher cannot be created.

### Example
```go
daemon, err := watch.NewDaemon(".", false)
if err != nil {
    return err
}
deffer daemon.Stop()

events := daemon.GetEvents(10)
for _, e := range events {
    fmt.Printf("[%s] %s %s\n", e.Time.Format("15:04"), e.Op, e.Path)
}
```
```

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

### Project Structure

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/types.md

Root context for tree and skyline visualization modes. Aggregates file list with rendering metadata. Supports filtering and diff analysis.

```go
type Project struct {
    Root      string       `json:"root"`
    Name      string       `json:"name,omitempty"`
    RemoteURL string       `json:"remote_url,omitempty"`
    Mode      string       `json:"mode"`
    Animate   bool         `json:"animate"`
    Files     []FileInfo   `json:"files"`
    DiffRef   string       `json:"diff_ref,omitempty"`
    Impact    []ImpactInfo `json:"impact,omitempty"`
    Depth     int          `json:"depth,omitempty"`
    Only      []string     `json:"only,omitempty"`
    Exclude   []string     `json:"exclude,omitempty"`
}
```

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

### Invalid CLI Flag Value Example

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/errors.md

Demonstrates an invalid value for the --depth flag, causing a parsing error. The CLI prints an error to stderr and exits.

```bash
codemap --depth abc .
# flag provided but not defined: -depth abc
```

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

### ProjectContext Go Struct

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/cmd-context.md

Provides high-level project metadata. Includes the project root, current branch, file count, detected languages, and counts of hub files.

```go
type ProjectContext struct {
    Root      string
    Branch    string
    FileCount int
    Languages []string
    HubCount  int
    TopHubs   []string
}
```

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

### Get Active Files

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/watch.md

Retrieves files that have been edited within a specified time duration, sorted by their most recent edit time. Useful for identifying recently modified files.

```go
func (ws *WorkingSet) ActiveFiles(since time.Duration) []WorkingFile
```

```go
recent := ws.ActiveFiles(1 * time.Hour)
fmt.Printf("Files edited in last hour: %d\n", len(recent))
for _, wf := range recent {
    fmt.Printf("  %s (%d edits)\n", wf.Path, wf.EditCount)
}
```

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

### Update Codemap

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/errors.md

If an artifact has an invalid schema version, updating the codemap tool to the latest version might resolve the issue. This command assumes you installed codemap via Homebrew.

```bash
brew upgrade codemap
```

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

### BuildFileGraph: Construct File Dependency Graph

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/api-reference/scanner.md

BuildFileGraph analyzes a project to return file-level dependencies with fuzzy import resolution. It handles Go package imports and TypeScript path aliases, returning a comprehensive dependency graph or an error on scan failure. Fuzzy resolution is used for import statements.

```go
graph, err := scanner.BuildFileGraph(".")
if err != nil {
    return err
}

// Who imports the router package?
importers := graph.Importers["pkg/router.go"]
for _, importer := range importers {
    fmt.Printf("%s imports pkg/router.go\n", importer)
}

// What does main.go import?
imports := graph.Imports["main.go"]
for _, imported := range imports {
    fmt.Printf("main.go imports %s\n", imported)
}
```

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

### Provide Stdin Input to Hook

Source: https://github.com/jordancoin/scoop-codemap/blob/main/_autodocs/errors.md

When a hook times out reading stdin, you can resolve it by explicitly providing input via a pipe. This example pipes a JSON string to the 'post-edit' hook.

```bash
echo '...' | codemap hook post-edit
```