# Audit Memory Reference

## Expected CLAUDE.md Locations

Packages that **should** have a CLAUDE.md (contain significant public API):

- `internal/docker/`
- `internal/containerfs/`
- `internal/config/`
- `internal/cmdutil/`
- `internal/iostreams/`
- `internal/workspace/`
- `internal/bundler/`
- `internal/socketbridge/`
- `internal/tui/`
- `internal/term/`
- `internal/hostproxy/`
- `internal/controlplane/`
- `internal/controlplane/firewall/`
- `internal/controlplane/overseer/`
- `internal/controlplane/agent/`
- `internal/controlplane/dockerevents/`
- `pkg/whail/`

Packages that **don't need** a CLAUDE.md (thin wiring, test-only, or generated):

- `internal/cmd/*/` — Covered by `.claude/rules/container-commands.md` and similar rules
- `*/mocks/` — Generated by moq, never hand-edited
- `*/gittest/`, `*/hostproxytest/`, `*/whailtest/` — Test helpers, self-documenting
- `internal/logger/` — Simple setup, covered in code-style rule
- `internal/prompter/` — Small, self-documenting

## Go Symbol Extraction Patterns

Exported identifiers in CLAUDE.md (backtick-wrapped):

```bash
grep -oE '`[A-Z][A-Za-z0-9]*`' file.md | tr -d '`' | sort -u
```

Exported symbols in Go source (excluding tests):

```bash
grep -E '^(func|type|var|const) [A-Z]' *.go | grep -v '_test.go' | sed 's/^.*:\(func\|type\|var\|const\) \([A-Za-z0-9]*\).*/\2/' | sort -u
```

For methods on types:

```bash
grep -E '^\s*func \([^)]+\) [A-Z]' *.go | grep -v '_test.go' | sed 's/.*) \([A-Za-z0-9]*\).*/\1/' | sort -u
```

## Auto Memory Audit

### Location

```
~/.claude/projects/-Users-<user>-Code-clawker/memory/
```

### MEMORY.md Index Validation

```bash
# Find memory files not referenced in MEMORY.md
for f in memory/*.md; do
  bn=$(basename "$f")
  [ "$bn" = "MEMORY.md" ] && continue
  grep -q "$bn" memory/MEMORY.md || echo "NOT INDEXED: $bn"
done

# Find broken links in MEMORY.md
grep -oE '\([^)]*\.md\)' memory/MEMORY.md | tr -d '()' | while read ref; do
  [ ! -f "memory/$ref" ] && echo "BROKEN: $ref"
done
```

## Mintlify Documentation Files

### Directory Structure

```
docs/
├── docs.json              # Mintlify config (theme, nav, colors, integrations)
├── custom.css             # Dark terminal theme overrides
├── favicon.svg            # >_ terminal prompt icon (amber on dark)
├── index.mdx              # Homepage
├── *.mdx                  # Hand-authored pages
├── assets/                # Image assets
└── cli-reference/         # Auto-generated (NEVER edit directly)
```

### Regeneration Command

```bash
go run ./cmd/gen-docs --doc-path docs --markdown --website
```

## Context Budget Guidelines

| Scope | Budget | Notes |
|-------|--------|-------|
| Root CLAUDE.md | ~200 lines | Always loaded |
| Root + always-loaded rules | < 500 lines | Rules without `paths:` frontmatter |
| Total always-loaded (+ global) | < 800 lines | Includes ~/.claude/CLAUDE.md |
| Each `internal/*/CLAUDE.md` | < 200 lines | Lazy-loaded per file access |
| Each `.claude/rules/*.md` | ~50-100 lines | Path-scoped load on demand |

## Staleness Thresholds

| Age | Severity | Action |
|-----|----------|--------|
| 0-30 days | OK | No action needed |
| 31-60 days | Warning | Review for accuracy |
| 61-90 days | Stale | Update or verify still correct |
| 90+ days | Critical | Likely outdated, prioritize update |
