1. Shapes Overview
Shapes describe the expected body structure for notes.
Schemas validate frontmatter and metadata.
Shapes validate headings, section organization, and structural consistency inside the note body.
Together they help keep vaults predictable as templates evolve over time.
Enable the Shape Engine in:
Settings → Shapes
What Shapes Are For
Shapes help standardize reusable note structures.
They are especially useful for:
- project notes
- meeting notes
- research workflows
- client records
- operational runbooks
- recurring templates
- dashboard source notes
Without Shapes, note structures gradually drift apart over time.
Examples:
- missing sections
- inconsistent heading order
- duplicated sections
- renamed headings
- partial templates
- abandoned structure patterns
Shapes help detect and repair those inconsistencies.
Shape Pieces
| Piece | Meaning |
|---|---|
| Shape note | A note in A-I/Forge/Shapes describing a reusable structure |
| Template note | A generated or refined structural template |
| Type target field | Frontmatter field used to match notes to shapes |
| Shape lint | Validates headings against the matching template |
| Shape repair | Inserts or reorders headings to match the template |
Typical Shape Workflow
A common workflow looks like this:
- Create shape notes in
A-I/Forge/Shapes - Enable template refinement
- Run Forge: Refine Shape Templates
- Enable shape heading validation
- Run Forge: Run Vault Lint
- Run Forge: Run Shape Repair (Dry Run)
- Review the preview carefully
- Run shape repair only after validation
Most users should begin with dry runs until they understand how their templates behave.
Matching Rules
A heading matches the template only when all three conditions match:
- heading text
- heading level
- parent heading chain
This prevents a heading like:
## Notes
under one section from satisfying:
## Notes
under a completely different section.
Forge validates the actual heading tree, not just isolated headings.
Tiny tree goblin defeated.
Recursive Tree Matching
Shape validation uses recursive tree matching.
That means Forge evaluates heading structure in context instead of flattening everything into one giant heading list.
This allows Shapes to detect:
- misplaced sections
- incorrect nesting
- duplicated branches
- structural drift
- broken template hierarchy
This becomes especially useful in larger operational or research notes with deep section trees.
Shape Lint
When enabled, Vault Lint can include shape validation findings.
Common findings include:
| Finding | Meaning |
|---|---|
shape_heading_missing | Required heading is absent |
shape_heading_order | Headings exist but appear in the wrong order |
shape_heading_extra | Heading exists outside the expected structure |
shape_section_empty | Required section exists but contains no direct content |
Shape lint helps identify gradual structural drift before templates become inconsistent across the vault.
Shape Repair
Shape Repair can automatically:
- insert missing headings
- restore heading order
- repair template structure
- standardize repeated note formats
Forge always recommends running:
Forge: Run Shape Repair (Dry Run)
before actual repair operations.
Template Refinement
Forge can generate or refine templates from shape notes.
This allows templates and validation rules to evolve together over time.
Template refinement is useful when:
- workflows mature
- note structures stabilize
- teams standardize formats
- recurring systems become consistent
Most users should treat refinement as gradual iteration instead of permanent rigid structure.
Shapes and Dataview
Consistent note structure improves more than readability.
It also improves:
- Dataview dashboards
- Bases
- exports
- automation workflows
- AI-assisted retrieval
- operational reviews
When notes share predictable sections, downstream tooling becomes dramatically more reliable.
Shapes and Ontology Indexes
Shapes work especially well alongside relationship indexes.
Shapes keep note structure predictable.
Relationship indexes help map how those structured notes connect across the vault.
Together they help larger vaults remain:
- navigable
- queryable
- understandable
- maintainable
Suggested Starting Point
Start small.
Do not attempt to shape every note type immediately.
Good first candidates include:
- project notes
- meeting notes
- research summaries
- operational runbooks
Simple templates usually age better than giant deeply nested structures.
