Engram Docs Skill Guide

Purpose: help humans and coding agents produce consistent, high-signal documentation for the Engram SDK docs site.

Scope

This guide applies to content in:

• docs/index.md
• docs/guide/*
• docs/api/*
• docs/architecture.md
• docs/troubleshooting.md
• docs/faq.md

Documentation Principles

1. Explain intent before mechanics
   • Start with "why this exists" and "when to use it".
2. Stay source-accurate
   • Match behavior to implemented code and current exports.
3. Optimize for operators
   • Include failure modes, guardrails, and recovery guidance.
4. Use concrete examples
   • Prefer real method names, config keys, and typed errors.
5. Separate immutable vs mutable behavior
   • Be explicit about CID immutability and index mutability.

Voice and Style

• Clear, technical, and direct.
• Avoid hype language and ambiguous claims.
• Use short sections with descriptive headings.
• Keep code snippets runnable and minimal.

Required Content Patterns

When documenting a method:

• Signature
• What it does
• Inputs
• Output shape
• Failure cases / typed errors
• Operational notes (cost, safety, retry, idempotency)

When documenting a config field:

• Type
• Default
• Operational impact
• Safe baseline value

Fundamentals Category Expectations

Fundamentals pages should always answer:

• What problem this solves
• How Engram models memory and trust
• What "autonomous" and "verifiable" mean in practice
• Which defaults are safe to start with

Change Checklist (before merge)

• [ ] Page links and sidebar entries are valid
• [ ] Terminology is consistent (CID, attestation, delegation, running spend)
• [ ] Config and env var names are exact
• [ ] Examples compile logically (imports and symbols exist)
• [ ] Docs build passes: cd docs && npm run docs:build

Avoid

• Documenting behavior not present in code
• Mixing roadmap ideas into reference pages without labels
• Long narrative with no actionable details
• Inconsistent naming (engramjs vs package internals) without context

Recommended Update Flow

1. Update docs page(s)
2. Rebuild docs locally
3. Spot-check navigation and search
4. Validate snippets against source exports
5. Keep this guide updated when standards evolve