Documents folder

The canonical document folder is:

./.neenja/

The reader recognizes document type by filename:

.neenja/documentation.md
.neenja/project-plan.md
.neenja/task-tree.yaml

If .neenja/documentation.md is missing, Neenja can still fall back to the legacy root file ./neenja.knowledge.md for documentation.

Documentation file

The documentation file starts with frontmatter:

---
title: <document title>
project: <project name>
version: 1
updated: <YYYY-MM-DD>
summary: <one sentence summary>
preferences: <optional single-line user documentation preferences>
---

If preferences: is present, it stores one line of user guidance for Neenja's documentation skills. The reader keeps it in metadata but does not render it in the main document body.

After frontmatter, documentation uses concept blocks:

## Concept: <Human Title>
ID: <stable-machine-id>
Privacy: <public|private>
Type: <concept|functions|types>
Category: <navigation group>
Tags: tag-one, tag-two
Summary: <one sentence summary>
Related: concept-id-one, concept-id-two

Documentation concept types

• Type: concept stores regular Markdown explanations, workflows, and notes.
• Type: functions stores important callable surfaces with repeatable #### Function: blocks.
• Type: types stores important project structures with repeatable #### Type: blocks.

Project plan file

The project plan file is a technical architecture and implementation-intent document. It starts with frontmatter:

---
title: <project name> Technical Project Plan
project: <project name>
version: 1
updated: <YYYY-MM-DD>
preferences: <optional single-line user technical preferences>
---

preferences: is optional. It stores stable technical preferences such as stack choices, architecture style, performance targets, security posture, exclusions, or preferred decision style.

After frontmatter, the plan uses ## Plan: blocks with optional ### detail blocks:

## Plan: <Human Section Title>
ID: <stable-machine-id>
Area: <Architecture|Runtime|Frontend|Backend|Data Contracts|Integrations|Infrastructure|Quality|Skills|Decisions>
Summary: <one sentence technical summary>

<Free-form technical Markdown. Use normal Markdown lists, tables, and code
blocks when they make the implementation intent clearer.>

### <Technical Detail Block>
<Free-form Markdown body for the detail block.>

The required section fields are ID and Area. Summary is optional and is rendered below the section title. Everything else in a section is ordinary Markdown. Content before the first ### heading is rendered as section intro Markdown, and each ### heading becomes a readable detail block with a free-form Markdown body.

The project plan should store architecture, module boundaries, data contracts, integration details, implementation constraints, and explicit user technical decisions. Task progress belongs in task-tree.yaml, not in the project plan.

Task tree file

The task tree file is YAML and stores a real nested tree:

title: <project name> Task Tree
project: <project name>
version: 1
updated: <YYYY-MM-DD>
preferences: <optional single-line user technical preferences>

tasks:
  - id: <stable-machine-id>
    title: <Human Task Title>
    status: <todo|in-progress|blocked|review|done|canceled>
    area: <Project|Frontend|Backend|Data|Infrastructure|Quality|Delivery|Docs|Skills>
    dependsOn:
      - <optional dependency task ID>
    details: |-
      <optional Markdown task detail, acceptance notes, or implementation hints>
    children:
      - id: <stable-machine-id>
        title: <Human Subtask Title>
        status: todo
        area: <area>

Nested children: creates decomposition edges. dependsOn: creates dependency edges between tasks, including across different parents. The task tree does not store summary; all task description, acceptance notes, and implementation hints belong in optional Markdown details. The reader calculates progress from task statuses and treats status: done as completed work.

Type links

When a function signature or the type part of a Parameters or Fields list item uses the same type name as a documented #### Type: entry, the reader turns that type name into a link to the matching type reference.