Issues / #116

Reusable directory treehouse (nimsforestdirectorytreehouse)

proposed feature Project: nimsforestdirectorytreehouse Reporter: 4 May 2026 17:48

Description

Build a generic, per-org-configurable directory treehouse so any community/org can plant a member-and-non-member directory on its own land. First customer: XR Valley (xrvalley.be), serving `directory.xrvalley.be`.

## Why
Directories are a recurring primitive (XR Valley today, immersive castles network and Brussels XR studios next). A purpose-built treehouse beats trying to retrofit a directory into Squarespace: SEO + agent crawlers need server-rendered HTML, JSON-LD `Organization` per page, a sitemap, a JSON feed, and an `llms.txt` — none of which Squarespace exposes cleanly.

## Repo
`nimsforestdirectorytreehouse` in the `nimsforest` GitHub org. Single repo, multiple binaries (source, treehouse, embed widget bundler) per the integration-repo pattern.

## Wind subjects (per org)
- `company.added`
- `company.updated`
- `company.verified`
- `company.featured`
- `company.removed`

## Sources (how entries get on Wind)
- **Self-service nim** in webchat — conversation flow collects fields (name, focus areas, contact, logo URL), validates, publishes on Wind. Open to members and non-members; verification is just a field.
- **Admin curation source** — gardener-branded UI for verify/feature/edit.
- **Bulk seed source** — one-shot CSV → events for the initial member list.

## Treehouse internals
- Deterministic in-memory projection rebuilt from the event log.
- Emits compost; Decomposer/bedrock handles canonical persistence to Soil. Treehouse never writes state directly.
- External enrichment (favicon fetch, og:image scrape, geocoding) goes through a taproot, not the treehouse.

## HTTP surface
- `/` — filterable index (industry, focus area, member/non-member, location)
- `/companies/{slug}` — per-company page, server-rendered, JSON-LD `Organization` + OpenGraph
- `/companies.json` — agent-friendly feed
- `/sitemap.xml`
- `/llms.txt`
- `/embed.js` + `/embed/featured` — widget for embedding featured cards on existing marketing sites (e.g. xrvalley.be on Squarespace)

## Per-org configuration
- Domain (CNAME → org land)
- Branding (logo, colors, copy)
- Taxonomy (industry/focus-area vocabularies)
- Curation rules (auto-publish vs. admin-verify-first)

## Deployment
- Container added to org role in `landconfigregistry`
- Planted via `land plant` on org land; joins org NATS via mycelium
- Domain via existing land cert flow
- CI tag → registry → land pulls

## XR Valley rollout
- XR Valley provisioned as a NimsForest org
- Treehouse planted on XR Valley org land
- `directory.xrvalley.be` CNAME'd to the org land
- Squarespace site at xrvalley.be links to the directory and embeds `/embed/featured` on relevant pages

## Relationship to other issues
- Supersedes the broad-scope Squarespace integration (#114) for the directory use-case. #114 should be narrowed to just the embed-widget integration (a thin Squarespace-side concern), not full Commerce API coverage.