Documentation

Concepts / Knowledge tree

Start shallow. Follow what matters.

A knowledge tree gives the agent candidates to inspect. Summaries and declared relationships help it choose the next step.

Indexes explain; the filesystem lists

A directory's index.md describes its purpose and rules. The directory's actual files and indexed subdirectories are its structural inventory. You do not need a second handwritten list of every child.

This illustrative SDLC tree separates two concerns:

.cumaru/
  index.md
  domain.md
  config.yaml
  specs/
    index.md
    authentication/
      index.md
      sessions.md
    payments/
      index.md

The authentication index introduces that area. Its session concern can describe the current session contract and reference the relevant source files.

Source: the recursive node model.

A summary helps select the next file

Each candidate has a short summary: in YAML frontmatter. cumaru tree reads those summaries without loading Markdown bodies. A valid summary is a trimmed string of 32 to 512 Unicode code points.

For a session-expiration task, the agent can choose authentication from the first list, then inspect its session concern. Payments can remain outside the task's context unless a relevant relationship leads there.

cumaru tree specs
cumaru tree specs/authentication
cumaru map specs/authentication/sessions.md

These paths are examples. Run the commands against paths that exist in your project.

Source: tree's candidates and summary contract.

Use different tools for different questions

  • tree lists candidate files and directories with their summaries.
  • map lists literal Markdown headings and line-range selectors.
  • get reads selected file ranges, such as a selector returned by map.
  • context ranks local Markdown by an English query. Scores are experimental relevance signals, not proof of correctness or completeness.

These commands help discover evidence. They do not decide which evidence answers the task.

Sources: map, get, and context.

Relationships give the tree meaning

In domains that declare them, depends-on: is a strong loading signal and relates: asks the agent to consider another concern. A reference table can connect a durable concern to source files. These relationships have different purposes; being nearby on disk does not make two concerns related.

An empty relationship list does not prove isolation. When a shared change may reach another concern, inspect relevant summaries and source references before fixing its scope.

Source: cross-reference discovery.

Stop at the relevant evidence

Expand one directory, select relevant candidates, and repeat only on the branches that survive. Read the selected bodies. Stop when further candidates and declared relationships add no relevant concern. A recursive audit with --deep is useful for checking a branch, not the default instruction to load it all.

Next: understand who owns each part of the tree.