# Mind Map Curation

Use this reference when working with docs-node shelf links, document links, heuristic correlation, or cleanup of a project documentation map.

## Operating Model

The docs-node mind map has two layers:

- `shelf_links`: parent/child relationships between shelves.
- `document_links`: directional links between documents.

Always distinguish the two layers in both execution and reporting. `manage_shelf_links` can create or update only `shelf_links`; it does not initialize `document_links`. A generic request such as "create the mind map" covers both layers unless the user narrows the scope or the agent explicitly excludes one layer with a reason.

Treat heuristic correlation as bootstrap/triage after shelf relationships have been considered. First decide whether shelves have parent/child relationships, then let `correlate` propose document links inside the same shelf or across pertinent shelves, and only apply the suggestions after reviewing a dry-run. Once an agent understands the functional context, add explicit manual links with `manage_document_links`.

## Create or Initialize a Mind Map

Use this workflow for a shelf that has no useful links yet, or when the user explicitly asks to initialize a map from scratch:

1. Run `feature_status` and record whether shelves, tags, `shelf_links`, and `document_links` are initialized.
2. Run `list_shelves` and identify candidate shelves. Exclude smoke/test shelves unless the user explicitly includes them.
3. State the intended scope before writes: only `shelf_links`, only `document_links`, or both.
4. Decide shelf relationships first. If a project/client shelf should inherit context from a standard/base shelf, add only small, relevant parent shelves with `manage_shelf_links`.
5. Run document-link heuristic correlation only after the shelf structure is known:
   - same-shelf discovery: `mode: "shelf"`, `scope: "shelf"`, `apply: false`;
   - child shelf with useful parents: `mode: "shelf"`, `scope: "shelf_with_parents"`, `apply: false`;
   - cross-shelf discovery without parentage: use only with explicit `target_shelves` and `apply: false`.
6. Review `sample_links`, target shelf names, confidence, signals, `candidate_links`, `skipped_low_confidence`, and `skipped_weak_signal` to decide whether the suggestions are pertinent.
7. Apply with `apply: true` only when samples are coherent, same-shelf or cross-shelf targets are appropriate, and `candidate_links > 0`.
8. If not applying, report the reason: zero candidates, low confidence, weak signals, corpus too large, ambiguous targets, or high noise risk.
9. Verify with `feature_status` and at least one representative `read_document` with `include_links: true`, `links_direction: "both"`, and a bounded `links_limit`.

Final reports must separate:

- `shelf_links` actions and status;
- `document_links` dry-run actions and status;
- applied writes;
- skipped writes and reasons;
- verification evidence.

## Maintain an Existing Shelf Map

Use this workflow when the shelf already has a map and the user adds, updates, reimports, or retags one or a few documents.

1. Update only the changed content first:
   - new or changed file: `scan_file` on that file;
   - changed folder batch: `scan_folder` only for the real changed documentation root;
   - retagging only: `set_document_tags` or `bulk_set_document_tags` only for the intended documents.
2. Resolve the affected `document_id`, shelf, current tags, and current links. Use `docs_navigation.read_document` with `include_links: true`, `links_direction: "both"`, and a bounded `links_limit`.
3. Check whether shelf parentage is still correct. Add or change `shelf_links` only when the new document reveals a durable structural relationship between shelves, not just a one-off topical similarity.
4. Run a targeted dry-run before adding document links:
   - one new document: `correlate` with `mode: "document"`, `document_id`, and `apply: false`;
   - several related new documents in a small shelf: `mode: "shelf"`, `scope: "shelf"`, and `apply: false`;
   - cross-shelf maintenance: use explicit `target_shelves`, and use parent scope only if the parent shelf relationship is already correct.
5. Review the same evidence as initialization: `sample_links`, confidence, signals, target shelf names, `candidate_links`, skipped counts, and whether the relation helps future navigation.
6. Apply only the pertinent links for the affected document set. If the agent knows the functional relation, prefer `manage_document_links` with a specific relation and `rationale` over accepting broad heuristic edges.
7. Do not rerun massive shelf-wide correlation for routine maintenance unless the user asks for a full refresh and accepts the noise/runtime risk.
8. Verify the updated nodes with `docs_navigation.read_document include_links: true`, `links_direction: "both"`, and a bounded `links_limit`.

Maintenance reports must separate:

- changed documents scanned or retagged;
- shelf parentage checked or changed;
- dry-run scope and candidates;
- document links applied manually or heuristically;
- skipped suggestions and reasons;
- representative link verification.

## Large Corpus Policy

For large shelves, do not run shelf-wide document correlation unless the user explicitly asks for it and accepts the noise/runtime risk. Treat a shelf as large when it has more than 500 documents or obviously broad coverage.

Prefer narrowing first by tag, subdomain, version, path, or explicit target shelves. Discover the available taxonomy with `list_tags` before choosing filters; do not hardcode shelf names or tag names from a specific workspace into the reusable workflow.

For large shelves, a valid result may be:

- `shelf_links` updated;
- document-link dry-run skipped or limited to a batch/tag;
- final report explicitly states why massive `document_links` correlation was not applied.

## Shelf Relationships

Use `manage_shelf_links` when a project-specific shelf should inherit context from a standard/base shelf.

```json
{
  "action": "manage_shelf_links",
  "operation": "set_parents",
  "shelf": "Cliente X",
  "parent_shelves": ["Framework Standard"]
}
```

Keep parent shelves small and relevant. If a parent contains thousands of documents or covers the wrong domain, remove it from `parent_shelves` and use `scope: "cross_shelf"` with explicit `target_shelves` only when needed.

## Bootstrap Correlation

Run correlation in dry-run first:

```json
{
  "action": "correlate",
  "mode": "shelf",
  "shelf": "Cliente X",
  "scope": "shelf_with_parents",
  "min_confidence": 0.5,
  "min_signal_count": 2,
  "apply": false
}
```

Review:

- `sample_links`
- `signals`
- `signal_count`
- `skipped_low_confidence`
- `skipped_weak_signal`
- target shelf names

Apply only if the sample is coherent:

```json
{
  "action": "correlate",
  "mode": "shelf",
  "shelf": "Cliente X",
  "scope": "shelf_with_parents",
  "min_confidence": 0.5,
  "min_signal_count": 2,
  "apply": true
}
```

Use `min_signal_count: 2` on corpora with generic tags, repeated technical families, duplicate scans, or noisy path proximity. Lower it only for intentionally broad discovery.

## Manual Links

After bootstrap, prefer manual links created at the moment the agent has enough context. Good manual links explain why a future reader should traverse the edge.

Useful relation names:

- `contains`: index or overview points to detail documents.
- `refined_by`: functional analysis points to technical analysis.
- `assessed_by`: request or idea points to feasibility assessment.
- `related_process`: documents describe adjacent steps of the same process.
- `troubleshoots`: diagnostic report explains a failure in a process document.
- `depends_on`: one document depends on another.
- `references_standard`: project document points to a standard/base document.
- `extends_standard`: project document customizes a standard/base behavior.

Avoid manual `same_topic` when a more operational relation is available.

Example:

```json
{
  "action": "manage_document_links",
  "operation": "add",
  "source_document_id": 101,
  "target_document_id": 202,
  "relation": "refined_by",
  "label": "Analisi funzionale -> analisi tecnica",
  "rationale": "Coppia funzionale/tecnica dello stesso requisito."
}
```

## Pruning Heuristic Noise

When heuristic links are noisy, remove only `origin="heuristic"` links. Never bulk-delete manual links during curation.

Dry-run first:

```json
{
  "action": "manage_document_links",
  "operation": "prune_heuristic_links",
  "shelf": "Cliente X",
  "max_confidence": 0.55,
  "apply": false
}
```

Then apply if candidates are correct:

```json
{
  "action": "manage_document_links",
  "operation": "prune_heuristic_links",
  "shelf": "Cliente X",
  "max_confidence": 0.55,
  "apply": true
}
```

For narrow cleanup, filter by `source_document_id`, `document_id`, `relation`, or `shelf`.

## Verification

After curation:

```json
{
  "action": "feature_status"
}
```

Then spot-check representative nodes with `docs_navigation`:

```json
{
  "action": "read_document",
  "document_id": 101,
  "include_links": true,
  "links_direction": "both",
  "links_limit": 20
}
```

The final map should have:

- relevant shelf parents only;
- manual links for high-value process relationships;
- heuristic links only where they remain useful discovery edges;
- no large generic parent shelf that dominates search or correlation.