# Aperture

> A markdown-first wiki and life system for agent-native work.
> It turns raw notes, links, transcripts, and daily logs into a browsable knowledge graph with source provenance, semantic trails, and agent APIs.

## Links

- [Repository](https://github.com/ZepPellN/Aperture)
- [README](https://github.com/ZepPellN/Aperture#readme)
- [Author](https://x.com/plutozeppln)

## What It Is

Aperture is a Next.js viewer that reads plain markdown files from your filesystem and compiles them into a structured knowledge system.
It is not a note-taking app. It is a lens: you keep writing markdown as you always have, and Aperture renders it as something you and your agents can explore.

## Core Capabilities

### Wiki System
- Article pages at `/wiki/<slug>` with rendered markdown, wikilink resolution, source provenance tracking, evolution timeline, backlinks, and semantic neighbor trails.
- Homepage with keyword + semantic search, category browsing, recently-updated timeline, and stats.
- Source provenance: every article tracks where its ideas came from (inline links, absorb logs, frontmatter, manual contributions) with contribution levels.

### Graph Exploration (4 views)
- **Network Graph** — Sigma.js WebGL force-directed graph. Focus mode, cluster highlighting, camera animation.
- **Topo Map** — Canvas-based topographic density visualization using D3 contours. Category-colored glows, hover tooltips.
- **Semantic Map** — Same topo visual language, laid out by UMAP semantic coordinates instead of force-directed placement.
- **Nest Graph** — React Three Fiber 3D organic cluster. Seed-shaped nodes, animated growing edges, orbit controls.

### Semantic Infrastructure
- UMAP dimensionality reduction from text embeddings.
- Cosine-similarity neighbor computation for semantic trails and random walk.
- DBSCAN clustering for knowledge islands at `/clusters`.

### Life Dashboard
- `/life` compiles daily journals, weekly intents, habit trackers, and goals into a unified dashboard.
- Weekly stats, intent cards (STOP/START/FORGIVE/SELF-CARE), next actions, mood timeline, habit heatmap, task velocity chart, life areas, and weekly reviews.

### Agent APIs
- `/api/wiki/<slug>` — JSON API returning slug, title, category, markdown, HTML, sources, backlinks, semantic neighbors, reading time, word count.
- `/llms.txt` and `/llms-full.txt` — agent-readable system descriptions.
- Bundled Claude Code skills in `.agents/skills/` for wiki maintenance.

## Core Routes

- `/` — Homepage: search, categories, recently updated, stats
- `/wiki/<slug>` — Article page with provenance, evolution, backlinks, mini graph
- `/graph` — Full-screen graph explorer with 4 view modes
- `/clusters` — Semantic cluster browser
- `/walk` — Random walk through semantic neighbors
- `/life` — Personal life dashboard
- `/api/wiki/<slug>` — JSON API for article data

## Data Format

- Source files: plain markdown with YAML frontmatter.
- Wikilink syntax: `[[slug|label]]`.
- Life data: custom markdown formats in `witness/` and `life-wiki/` directories.
- No database. No proprietary format. File-over-app.

## Agent Onboarding

Tell your agent to read `AGENT_SETUP.md` for full setup: vault scaffolding, skill installation, content ingestion, and viewer launch.