Imported from pablof7z/hl (AGENTS.md). Install upstream with npx skills add pablof7z/hl. Copyright stays with the author.

AGENTS.md — Highlighter

This is a monorepo. Each subproject has its own AGENTS.md with specific commands and conventions. The closest AGENTS.md to the file you're editing takes precedence.

Project Overview

Highlighter is a Nostr-native social reading platform built around NIP-29 relay-based groups. Users create and join communities where they share artifacts (books, articles, podcasts, videos), annotate them with highlights (compelling excerpts), and spark discussions. Growth is baked into every surface — not a separate department.

Key differentiators:

• Nostr-native from day one — communities are NIP-29 groups, users own their keys, data is portable
• The artifact is the hero — everything organizes around source content, not ephemeral posts
• Growth is the product — every interaction is designed for virality loops and user-controlled sharing

Repository Structure

highlighter/
├── relay/          # Go relay (Croissant by fiatjaf) — NIP-29 groups, search, Blossom media, LiveKit
├── web/            # Web SPA (SvelteKit or similar) — primary client surface
├── app/            # Rust core + native UI (Kotlin/Swift) — mobile & desktop
├── docs/           # Product specs, architecture docs, market research, wireframes
├── .agents/        # TENEX agent configurations and skills
└── AGENTS.md       # You are here

Note: /relay, /web, and /app are scaffolded from their respective AGENTS.md files. The repo currently holds docs and specs; code directories will be created as development begins.

Tech Stack

Key NIPs

Content Event Model

Highlighter does not define a made-up artifact kind like 30403.

• Artifact shares use kind:11 threads inside NIP-29 groups
• Artifacts are identified by source references and metadata tags, not a dedicated custom event kind
• Highlights use kind:9802
• Discussion replies use kind:1111

Getting Started

The repo is in early specification phase. No build commands exist yet. When code directories are scaffolded:

1. Navigate to the subproject directory
2. Read that directory's AGENTS.md for setup and dev commands
3. Follow platform-specific instructions

Deployment

• Manual deployment: deploy the web app from the repo root with npm run deploy:web:prod.
• That command builds web/ and runs vercel deploy --prebuilt --prod, which is the path currently serving beta.highlighter.com.
• Validate the result on beta.highlighter.com. The relay is in relay.highlighter.com (running in this computer behind Caddy)
• Do not rely on Git-based auto deployment for the current web app setup.

Documentation

All product and architecture docs live in /docs:

Architecture Decisions

Why Croissant?

Croissant (by fiatjaf) is a full-featured NIP-29 relay built on khatru. It provides group lifecycle, membership, moderation, full-text search (Bleve), Blossom media upload, and LiveKit audio rooms out of the box. We fork and customize rather than building from scratch. See docs/technical-architecture.md §2.

Why Rust core for mobile/desktop?

Shared protocol logic (Nostr client, NIP-29, signing, sync) across all native platforms via FFI bridge. Only the UI layer differs per platform.

Why NIP-29 groups (not DMs or channels)?

Groups are relay-native, portable, have built-in membership/role/moderation semantics, and support the four access×visibility combinations Highlighter needs. See docs/technical-architecture.md §3.

• If using XcodeBuildMCP, use the installed XcodeBuildMCP skill before calling XcodeBuildMCP tools.