Documents & Layout

Every Archcore document is a markdown file stored under .archcore/. The filename carries the document type, and the directory structure around it is yours to choose.

File naming

Every document follows the pattern:

<slug>.<type>.md

• Slug: lowercase alphanumeric with hyphens. Must match ^[a-z0-9]+(-[a-z0-9]+)*$
• Type: one of the 21 valid types (see Document Types)
• Extension: always .md

Valid: jwt-strategy, use-postgres, api-v2-migration

Invalid: JWT_Strategy (uppercase), use postgres (spaces), my.decision (dots in slug), jwt_strategy (underscores)

If a filename has no recognized type segment, the scanner categorizes the document as knowledge. archcore status reports such a file as an error with the message filename must match <slug>.<type>.md.

Examples

jwt-strategy.adr.md           # decision record
api-error-format.rule.md      # enforced standard
setting-up-ci.guide.md        # step-by-step how-to
auth-redesign.prd.md          # product requirements
callbacks-to-async.cpat.md    # code pattern change

Free-form directories

The directory structure inside .archcore/ is free-form. Organize documents by domain, feature, team, or any structure that fits your project.

Categories (vision, knowledge, experience) are virtual. Archcore derives them from the document type in the filename, not from the physical directory. Moving a file between directories never changes its category.

Other rules:

• Hidden directories (starting with .) are ignored
• Nesting depth is unlimited
• Directory names have no restrictions (lowercase with hyphens recommended)

The legacy layout with vision/, knowledge/, and experience/ directories still works. The scanner treats them as ordinary directories with no special meaning, so no migration is needed.

Run archcore status to check the filename format and the type validity of every document, or call the MCP tool list_documents to see documents with their virtual categories, independent of the directory layout.

Start flat

You don’t need to design the perfect directory tree upfront. Put documents in the root of .archcore/. Organize into subdirectories when you have 10+ documents and want to group them.

Recommended layouts

Small project (1-5 documents)

Keep it flat. No subdirectories needed.

.archcore/
  settings.json
  use-typescript.adr.md
  coding-standards.rule.md
  setup.guide.md

Growing product team (5-20 documents)

Organize by domain or feature area.

.archcore/
  settings.json
  coding-standards.rule.md
  auth/
    jwt-strategy.adr.md
    auth-setup.guide.md
  payments/
    stripe.adr.md
  roadmap/
    q1-goals.prd.md
    auth-v2.plan.md

Platform / infrastructure repo (20+ documents)

Organize by domain with deeper nesting as needed.

.archcore/
  settings.json
  api/
    versioning.adr.md
    error-format.rule.md
    rate-limiting.rule.md
  auth/
    jwt-strategy.adr.md
    auth-rules.rule.md
    auth-redesign.prd.md
  infrastructure/
    k8s-migration.adr.md
    deployment-checklist.guide.md
  patterns/
    api-endpoint-creation.task-type.md
    error-handling-v2.cpat.md

You can also organize by team (backend/, frontend/, platform/) or mix approaches, such as top-level rules with domain-specific subdirectories. Pick whatever makes documents easy to find.

Special files

File	Purpose
settings.json	Required. Sync configuration and language settings
.sync-state.json	Auto-generated and tracked in git, so it is shared with the team. Stores document relations and sync hashes

The CLI manages both files and skips them when scanning documents.

Next steps

• Document Types lists all 21 types and when to use each.
• The Plugin quick start and the CLI quick start walk through creating your first document.
• MCP Server explains how AI agents read and write project context.