Reference instance seeding

This prompt depends on the graph migration already being complete and working. Before starting, confirm that:

• GET /api/nodes returns nodes with relations[] arrays
• The relations_index table exists in the database
• The left panel has tree / position / graph mode tabs

If any of those are not working, stop and complete the graph migration first.

What this prompt does

Seeds the LFTI reference instance — the canonical methodology layer that defines what each tool, principle, and phase means. This is not project data. It is the living documentation of the participatory methodology that LFTI uses and that partner institutions can see and learn from.

Read codeReference/PLA_TOOLS_REFERENCE.md fully before writing a single line of seed code. That document is the source of truth. Everything you build here comes from it.

Also re-read the existing seedLFTI() function in lfti-spine.html to understand the existing node structure before adding to it. You are extending the seed, not replacing it.

Structure to build

The reference instance sits as a parallel branch under the root LFTI node, connected by a contains relation. It does not replace or reorganise the existing node tree.

LFTI (root, already exists)
  ├── [existing nodes — unchanged]
  └── Reference Instance              ← new, add here
        ├── Principles & Ethos        ← methodology layer
        │     ├── [one node per principle]
        ├── Gather Phase              ← reference phase node
        │     ├── [one node per tool]
        │     │     └── [block nodes for variants/steps where specified]
        ├── Collate Phase
        │     ├── Collaborative Prioritisation  ← tool category node
        │     │     └── [tool nodes]
        │     ├── Diagramming                   ← tool category node
        │     │     └── [tool nodes]
        │     └── [remaining collate tools]
        ├── Present Phase
        │     └── [tool nodes]
        └── Cross-cutting Tools
              └── [tool nodes]

Node construction rules

Read codeReference/PLA_TOOLS_REFERENCE.md seeding instructions section (at the bottom of that document). They are authoritative. Summary:

Tool nodes:

{
  "type": "tool",
  "meta": {
    "_level": "reference",
    "_visibility": "partners",
    "phase": "gather"           // or collate / present / cross-cutting
  }
}

Principle nodes:

{
  "type": "note",
  "meta": {
    "_level": "reference",
    "_visibility": "partners",
    "category": "principle"
  }
}

Placeholder nodes (Synthesis canvas):

{
  "meta": {
    "_level": "reference",
    "_placeholder": true,
    "_placeholder_note": "Collaborative canvas deferred. Node holds shape."
  }
}

Body Map specifically:

{
  "meta": {
    "_level": "reference",
    "_facilitation_owner": "Kamoto/Mary Manzole",
    "_status": "protocol_pending",
    "_status_note": "Full facilitation protocol to be documented with Mary Manzole. Do not use without that protocol."
  }
}

Node bodies: Copy the description and key content from PLA_TOOLS_REFERENCE.md directly into node bodies. Do not summarise or paraphrase — these are reference nodes and their body text is their value. Facilitation steps go in the body as prose, not as child nodes.

Node titles: Use the ### heading text from the reference document exactly, prefixed with the phase abbreviation where helpful for disambiguation. E.g. “Gather — Transect Walk”, “Collate — Matrix Ranking”.

Relations to add

From Reference Instance node to phase nodes:

{ "type": "contains", "target": "ref_gather_phase" }
{ "type": "contains", "target": "ref_collate_phase" }
{ "type": "contains", "target": "ref_present_phase" }
{ "type": "contains", "target": "ref_principles" }

From LFTI root to Reference Instance:

{ "type": "contains", "target": "ref_instance" }

From tool nodes to existing institution nodes (provenance):

• Body Map → { "type": "involves", "target": "kamoto" } (Kamoto node already exists in seed)
• Pre-perceptions → { "type": "involves", "target": "glm" } (GLM node already exists)
• PPP tools generally → { "type": "involves", "target": "kamoto" }

From existing cycle nodes to reference phase nodes (instance references methodology): For each of the twelve cycle nodes already in the seed (Past→Gather, Past→Collate, etc.):

{ "type": "references", "target": "ref_gather_phase" }  // or collate / present

From Pre-perceptions tool node to Whole cycle Gather node:

{ "type": "feeds", "target": "cycle_whole_gather" }

This represents that the second pre-perceptions instance runs in the Whole cycle’s Gather phase.

IDs

Use a consistent prefix scheme:

• ref_ — reference instance root and phase nodes
• ref_p_ — principle nodes (e.g. ref_p_handing_over_stick)
• ref_g_ — gather tool nodes (e.g. ref_g_transect_walk)
• ref_g_b_ — gather tool block/variant nodes
• ref_c_ — collate tool nodes
• ref_c_cat_ — collate tool category nodes
• ref_pr_ — present tool nodes
• ref_x_ — cross-cutting tool nodes

Where to add the seed code

Add a new function seedReferenceInstance() in lfti-spine.html immediately after the existing seedLFTI() function. Call it from the boot sequence after seedLFTI():

seedLFTI();
seedReferenceInstance();
loadDB();
saveDB();

seedReferenceInstance() should check if the reference instance root node already exists before seeding, to make the boot sequence safe to run multiple times:

function seedReferenceInstance() {
  if (state.nodes['ref_instance']) return; // already seeded
  // ... seed code
}

Visual treatment in the UI

Reference instance nodes already get visual treatment from the graph migration (ref badge, dimmed title, read-only styled inputs). Confirm this is working correctly for the new nodes.

In the left panel position mode, reference nodes should appear when the matching movement/phase filters are active — so when a facilitator is looking at “Gather phase” in position mode, they see both the real project’s Gather nodes AND the reference Gather tool nodes together. This is intentional: the reference is not hidden away, it is visible alongside the live work as a resource.

To enable this, reference tool nodes need meta.phase set to their phase value (already specified above). Position mode filtering should already pick this up if it filters on meta.phase — confirm this works and adjust the position mode filter logic if needed.

Expanded node set for position mode

Now that reference tools are in the system, extend the position mode context filter to include:

[ UK ] [ NZ ] [ Zambia ] [ cross-cohort ] [ reference ] [ all ]

A reference context filter shows only _level: "reference" nodes. This gives facilitators a clean way to browse the tool library while in position mode — “show me all Gather tools” by selecting phase:gather + context:reference.

What does NOT change

• Existing seed nodes — unchanged
• Existing API endpoints — unchanged
• Existing tree view — unchanged (reference nodes appear in tree under their parent)
• Temporal navigation — unchanged
• Image attachments — unchanged
• Footer bar — unchanged

When you’re done

Test these five things in order:

1. Boot the server fresh (or clear and reseed). GET /api/nodes returns reference instance nodes with correct meta._level: "reference" and relations[] arrays including involves relations to Kamoto and GLM where specified.

2. In the left panel tree view, navigate to the Reference Instance node. Expand it. The full hierarchy is visible: Principles & Ethos, Gather Phase, Collate Phase, Present Phase, Cross-cutting Tools, each with their child tool nodes.

3. Select the Body Map node. Confirm: ref badge visible, inputs styled read-only, meta._status: "protocol_pending" visible somewhere in the content section (add a small status indicator if not already present for _status meta values).

4. Switch to position mode. Select phase: Gather, context: reference. The Gather tool nodes appear as cards — Observation, Semi-structured Interview, Transect Walk, Body Map, Photo Walk, Story Circle, River of Life, Peer Interview, Learning Journal, Timeline, Focus Group, Pre-perceptions. No live project nodes appear.

5. Select phase: Gather, context: all. Both reference tool nodes AND live project Gather nodes appear together. The reference nodes have the ref badge; the live nodes do not.

← All notes · More from LFTI