cl-memcached Documentation Index

January 21, 2026 · View on GitHub

Complete documentation generated from Canon specification. Generated: 2026-01-21

For Users (Getting Started)

Start here: docs/README.md — Overview and navigation
First success: docs/quickstart.md — Get running in 5 minutes
Understand concepts: docs/concepts/core-concepts.md — What memcached does
Look up functions: docs/reference/api-reference.md — Complete API
How-to guides: docs/how-to/ — Solve specific problems

For Agents/Developers (Implementation)

Start here: CLAUDE.md — Implementation contract, 19 sections
Skills reference: SKILL.md — Agent-optimized skill template
Full specification: canon/canon.yaml — Complete architecture
Design rationale: .canon-initiation/git-archaeology.md — Why decisions were made

Documentation Structure

cl-memcached/
├── docs/                           # User-oriented (humans)
│   ├── README.md                   # Entry point with navigation
│   ├── quickstart.md               # 5-minute tutorial
│   ├── concepts/
│   │   └── core-concepts.md        # Memcached fundamentals
│   ├── reference/
│   │   └── api-reference.md        # Complete API reference
│   └── how-to/
│       └── connection-pooling.md   # Performance optimization
│
├── CLAUDE.md                       # Agent-oriented implementation spec (29KB)
├── SKILL.md                        # Agent skill template (13KB)
├── README.md (original)            # Original project README (enhanced)
│
└── canon/                          # Formal specification (extracted from code)
    ├── canon.yaml                  # Complete manifest
    ├── core/
    │   ├── foundation/
    │   │   └── vocabulary.md       # 9 core concepts
    │   └── properties/
    │       └── system-invariants.md # 29 properties
    └── features/                   # 7 feature areas
        ├── connection/contracts/
        ├── storage/contracts/
        ├── retrieval/contracts/
        ├── counters/contracts/
        ├── stats/contracts/
        ├── utility/contracts/
        └── meta-protocol/contracts/ + scenarios/

Document Details

User-Oriented (docs/)

Document	Purpose	Audience	Length
README.md	Entry point, navigation, quick example	New users	~500 lines
quickstart.md	Get running in 5 minutes	Impatient developers	~200 lines
core-concepts.md	Understand memcached fundamentals	Learning	~400 lines
api-reference.md	Function signatures, parameters, returns	API lookup	~600 lines
connection-pooling.md	Enable 5-7x speedup	Performance optimization	~250 lines

Key characteristics:

Progressive disclosure (basic → advanced)
Real, tested examples
Error troubleshooting sections
Clear navigation between documents
Assumes: Intermediate Lisp, new to memcached

Agent-Oriented (Root level)

Document	Sections	Purpose	For
CLAUDE.md	19 sections	Implementation spec	Agents implementing features
SKILL.md	15 sections	Skill template	Agents using cl-memcached

CLAUDE.md sections:

Scope & Applicability
Terminology (25 terms)
Type Constraints (8 tables)
Normative Rules (10 RULE-NNN)
System Invariants (7 INV-NNN)
Anti-Patterns (5 forbidden structures)
Heuristics (4 probabilistic signals)
Operation Semantics (SET, GET, CAS, counters)
Error Conditions (connection, type, missing key)
Allowed Transformations
Forbidden Transformations
Ambiguity Resolution Order
Machine Checklist (16 binary assertions)
Protocol Rules (TEXT vs META)
Pipelining Constraints
Exemplar Patterns (5 complete working examples)
Implementation Verification
Debugging Guidance
Conformance Checklist (40 items)

SKILL.md sections:

When to invoke
Core competencies
Architecture summary
Operation reference
Protocol comparison
Exemplar operations (4 patterns)
Error handling patterns
Global configuration
Performance tuning
Type constraints
Debugging checklist
Conformance requirements
Implementation workflow
Reference documents
Verification

Canon Specification (canon/)

Formal extracted specification from code analysis:

File	Type	Contents	Confidence
canon.yaml	Manifest	Project metadata, feature inventory, metrics	0.94
vocabulary.md	Definitions	9 core concepts (key, value, TTL, CAS, etc.)	1.0
system-invariants.md	Properties	29 invariants across 12 categories	0.96
/contracts/	Contracts	31+ function specifications across 7 features	0.95
/scenarios/	Tests	20+ behavioral scenarios from test suite	0.95

Usage Guidance

If you're a human user starting with cl-memcached:

1. Read: docs/README.md (overview, 5 min)
2. Do: docs/quickstart.md (hands-on, 5 min)
3. Learn: docs/concepts/core-concepts.md (theory, 15 min)
4. Refer: docs/reference/api-reference.md (when coding)
5. How-to: docs/how-to/ (for specific problems)

If you're an agent implementing cl-memcached features:

1. Read: CLAUDE.md (entire spec, understand rules/invariants)
2. Reference: SKILL.md (operation patterns, error handling)
3. Implement: Follow exemplar patterns (PATTERN-001 through PATTERN-005)
4. Verify: Run conformance checklist (machine checklist in CLAUDE.md)
5. Test: Use test patterns from canon/features/*/scenarios/

If you're onboarding a team:

1. Share: docs/README.md + docs/quickstart.md (30 min)
2. Share: docs/concepts/core-concepts.md (1 hour)
3. Share: docs/reference/api-reference.md (reference)
4. For specs: CLAUDE.md + SKILL.md
5. For architecture: canon/canon.yaml + git-archaeology.md

Content Statistics

User Documentation (docs/)

Total documents: 5
Total lines: ~2000
Code examples: 40+
Tables: 15+
Cross-references: 30+
Readability: Progressive disclosure, no walls of text

Agent Documentation (root)

CLAUDE.md: 19 sections, 800+ lines, 25 rules/invariants, 5 patterns
SKILL.md: 15 sections, 400+ lines, 4 patterns, 40+ examples
Total: 1200+ lines of agent-optimized spec

Canon Specification

Contracts: 31+ function specifications
Scenarios: 20+ behavioral tests
Invariants: 29 system properties
Coverage: 7 feature areas (connection, storage, retrieval, counters, stats, utility, meta-protocol)
Confidence: Overall 0.94 (very high)

Quality Assurance

Verification Checklist

[✓] All human docs follow doc-writer-for-humans pattern
    - Progressive disclosure
    - Real examples
    - Error handling sections
    - Navigation present

[✓] All agent docs follow doc-writer-for-agents pattern
    - RULE-NNN format for normative rules
    - INV-NNN format for invariants
    - PATTERN-NNN format for exemplars
    - ANTI-NNN format for forbidden patterns
    - Machine checklist present
    - Dense notation (tables, DOT, BNF)
    - RFC 2119 keywords (MUST, SHOULD, MAY)

[✓] Cross-linking verified
    - docs/README.md links to all sub-docs
    - CLAUDE.md references Canon spec
    - SKILL.md links to detailed docs

[✓] Accuracy verified against Canon
    - All operations match Canon contracts
    - All error conditions match error spec
    - All invariants match system properties
    - All patterns derived from scenarios

[✓] Completeness verified
    - All 31+ functions documented
    - All 7 feature areas covered
    - All 29 invariants documented
    - All error conditions documented

Generation Metadata

Generated: 2026-01-21
Method: Multi-source triangulation (code + docs + tests + git history)
Overall confidence: 0.94 (very high)
Canon status: Production-ready

Artifacts Generated

5 human-oriented documents in docs/
2 agent-oriented documents (CLAUDE.md, SKILL.md)
1 index document (this file)
20+ Canon specification files (canon/)
6 initiation artifacts (.canon-initiation/)

Document Quality Metrics

Metric	Value
Code examples	40+
Tables	20+
Cross-references	50+
Rules/Invariants	35
Patterns	9
Functions documented	31+
Lines of documentation	2000+ user + 1200+ agent
Confidence level	0.94

Updating Documentation

When code changes:

Update Canon contracts: canon/features/*/contracts/
Update scenarios if behavior changes: canon/features/*/scenarios/
Update CLAUDE.md rules/invariants as needed
Update docs/ examples if public API changes

When adding features:

Add contract: canon/features/[new-feature]/contracts/
Add scenarios: canon/features/[new-feature]/scenarios/
Update CLAUDE.md (rules, patterns)
Update SKILL.md (operations section)
Update docs/reference/api-reference.md
Update docs/README.md (table of contents)

Document maintenance:

Keep Canon spec as source of truth
Derive docs from Canon (not vice versa)
Run tests to verify examples remain correct
Use doc-writer skills for formatting consistency