<img src="docs/preview.jpg" alt="The Luia graph: team knowledge at the centre, project work fanning out around it, with one node selected to show its connections" width="100%">

# Luia

**A knowledge graph for design teams.**

Design teams accumulate knowledge faster than they can organise it. A spacing
rule agreed in March, a carousel pattern that tested badly, the reason a
component was built one way and not another. It ends up scattered across docs,
threads, and people's memory, and by the time someone needs it nobody can find
it.

Luia has two halves:

- **An MCP server** that plugs into Claude. Designers and developers install it
  once, and from then on Claude reads the team's conventions before answering
  and writes new decisions back as they are made.
- **A graph viewer** that renders the same knowledge spatially, so you can see
  how decisions connect instead of scrolling a folder tree.

Both read the same plain Markdown folder. There is no database, no backend, and
no service to sign up for — which means a team shares its knowledge by putting
that folder in git.

## Install the MCP server

Requires [Node.js](https://nodejs.org) 20.19+ or 22.12+.

```bash
git clone https://github.com/gustavocambareri/Luia_MCP.git
cd Luia_MCP
npm install
```

Point Claude at it. `LUIA_KNOWLEDGE_DIR` is the folder your team's Markdown
lives in — anywhere you like:

```bash
claude mcp add luia --scope user \
  --env LUIA_KNOWLEDGE_DIR="$HOME/luia-knowledge" \
  -- node "$PWD/server/index.mjs"
```

Verify it connected:

```bash
claude mcp list        # luia: … - ✔ Connected
```

For Claude Desktop, add the same thing to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "luia": {
      "command": "node",
      "args": ["/absolute/path/to/luia/server/index.mjs"],
      "env": { "LUIA_KNOWLEDGE_DIR": "/absolute/path/to/your-knowledge" }
    }
  }
}
```

That's the whole setup. Ask Claude *"what's our spacing rule?"* and it searches
the store before answering.

### What Claude can do with it

| Tool | When Claude reaches for it |
| --- | --- |
| `search_knowledge` | Before answering anything about how your team designs or builds — so the answer matches decisions you already made |
| `get_document` | When a search excerpt looks relevant and it needs the full rule |
| `record_decision` | The moment you settle a convention, so it survives the session |
| `list_documents` | To see everything the team has written down |

The two that matter are **search** and **record**. Search is described so Claude
calls it unprompted at the start of design work — nobody remembers to ask for
their own conventions. Record is a single call with no ceremony, because a
capture step with friction is a capture step that doesn't happen.

### Using it with your team

The knowledge store is a folder of Markdown files, so sharing it is just git:

```bash
cd ~/luia-knowledge
git init && git add . && git commit -m "Team knowledge"
git remote add origin git@github.com:your-team/design-knowledge.git
git push -u origin main
```

Teammates clone that repo and point their own `LUIA_KNOWLEDGE_DIR` at it. Pull
to get everyone's decisions; push to share yours. Decisions arrive as readable
diffs you can review like any other change.

Each document is plain Markdown with frontmatter — editable by hand, no tool
required:

```markdown
---
title: Spacing System
project: atlas          # optional; omit for team-wide knowledge
author: your-name       # or 'team' for collectively-owned decisions
tags: [spacing, layout]
created: 2026-03-09
---

8px base unit, with a 4px step for tight UI.

**Why:** the ratio between gaps carries more meaning than absolute values.
```

> [!TIP]
> Always write the **why**. A decision without its rationale is one the team
> relitigates in six weeks — and the rationale is what makes Claude apply the
> rule correctly to a case you didn't anticipate.

## The graph viewer

- **Spatial navigation** — a 3D force-directed graph you can pan, zoom, and
  explore, with hand-composed positions so the layout reads deliberately
  rather than like a hairball.
- **Four ways to filter** — by scope, project, author, or free-text search
  across titles, tags, descriptions, and section headings.
- **The author lens** — dim everything except one person's contributions to see
  who holds which knowledge, and where a single point of failure is forming.
- **Typed relationships** — `foundation`, `reference`, and `sibling` edges are
  drawn differently, so how two documents relate is legible at a glance.
- **Readable content** — every node carries full Markdown, a description, and a
  section outline; click any node to read it without leaving the graph.

### Running the viewer

```bash
npm run dev
```

Open the address Vite prints (usually `http://localhost:5173`) and the demo
graph loads immediately.

```bash
npm run build     # production build to dist/
npm run preview   # serve that build locally
npm run lint      # eslint
```

> [!NOTE]
> The bundled graph is **entirely fictional**. Meridian, Lumen, Atlas, Cadence,
> Harbor, and Verso are invented engagements, and every person credited in them
> is made up. Nothing here is real client work.

### Viewer data format

The viewer reads `src/data/graph-data.json`. Replace it with your own and the
app is yours.

A node looks like this:

```json
{
  "id": "projects/atlas/block-library",
  "name": "Atlas — Block Library",
  "slug": "block-library",
  "scope": "project",
  "project": "atlas",
  "author": "your-name",
  "tags": ["atlas", "blocks", "templates"],
  "created": "Mon Mar 16 2026 01:00:00 GM",
  "fileSize": 8200,
  "description": "Reusable blocks and page templates for the Atlas redesign.",
  "body": "# Atlas — Block Library\n\n## Navigation\n\nSticky header that…",
  "sections": ["Atlas — Block Library", "Navigation"],
  "connections": ["_team/design-system-patterns"]
}
```

And an edge connects two of them:

```json
{
  "source": "_team/design-system-patterns",
  "target": "projects/atlas/block-library",
  "type": "reference",
  "label": "informs",
  "description": "Team patterns applied in the Atlas block library."
}
```

The full shape is defined in [`src/lib/types.ts`](src/lib/types.ts).

### Fields worth understanding

| Field | What it does |
| --- | --- |
| `scope` | `team` for shared knowledge, `project` for engagement work. Drives colour and grouping. |
| `project` | Required when `scope` is `project`. Becomes a filter chip automatically. |
| `author` | Powers the author lens. Use `team` for collectively-owned documents. |
| `fileSize` | Controls node radius. Scale your values into roughly `2600–19500` so sizes stay differentiated. |
| `body` | Markdown, rendered in the detail panel. |
| `sections` | Heading list, included in search. |
| `type` | Edge weight and curvature: `foundation` arcs through the centre, `sibling` hugs the perimeter. |

### Adding a project

1. Add your nodes to `graph-data.json` with a new `project` value.
2. Add a colour for it in [`src/lib/colors.ts`](src/lib/colors.ts) → `PROJECT_COLORS`.
   Without one it falls back to the default ink, and becomes indistinguishable
   from team nodes.
3. Optionally place its nodes in `MANUAL_POSITIONS` in
   [`src/components/graph3d/useForceLayout.ts`](src/components/graph3d/useForceLayout.ts).
   Nodes without coordinates are positioned automatically, but hand-placing
   them keeps clusters legible.

The filter chips read the project list straight from your data, so step 1 is
enough to make it appear in the UI.

> [!TIP]
> Keep `id` values path-like (`projects/<project>/<slug>`). Nothing enforces it,
> but it keeps the file browsable and makes `connections` easy to write by hand.

## Design decisions

A few choices are deliberate and worth knowing before you extend it:

- **Positions are authored, not simulated.** A pure force layout drifts on every
  reload and buries the structure. Coordinates live in `useForceLayout.ts` so
  the composition is stable and intentional.
- **Colour is a system, not decoration.** Every hue in `colors.ts` is derived
  from a five-colour palette and tuned to a narrow contrast band, so no project
  reads as visually heavier than another.
- **Uppercase titles, explicit weights.** Type rules are applied consistently
  across the canvas and panel; if you add UI, set `fontWeight` explicitly rather
  than inheriting it.

## Project structure

```
server/                       # the MCP server
├── index.mjs                 # tool definitions + stdio transport
└── knowledge.mjs             # Markdown store: read, write, search

src/                          # the graph viewer
├── data/graph-data.json      # demo content — replace this with yours
├── lib/
│   ├── types.ts              # GraphNode, GraphEdge, GraphData
│   └── colors.ts             # palette, scope/project/author colour maps
├── hooks/useGraphData.ts     # filtering, search, selection state
└── components/
    ├── FilterBar.tsx         # scope/project/author filters, search
    ├── DecisionLog.tsx       # per-node detail panel
    └── graph3d/              # the 3D scene
        ├── useForceLayout.ts # hand-placed node coordinates
        ├── GraphNode3D.tsx   # node + label rendering
        └── GraphEdge3D.tsx   # typed, curved edges
```

## Built with

[React 19](https://react.dev) · [TypeScript](https://www.typescriptlang.org) ·
[Vite](https://vite.dev) · [Three.js](https://threejs.org) via
[React Three Fiber](https://r3f.docs.pmnd.rs) ·
[Tailwind CSS](https://tailwindcss.com)