diff --git a/packages/plugins/plugin-llm-wiki/.gitignore b/packages/plugins/plugin-llm-wiki/.gitignore new file mode 100644 index 00000000000..0430cc35608 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/.gitignore @@ -0,0 +1,3 @@ +dist +node_modules +.paperclip-sdk diff --git a/packages/plugins/plugin-llm-wiki/README.md b/packages/plugins/plugin-llm-wiki/README.md new file mode 100644 index 00000000000..8ac0e38c16e --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/README.md @@ -0,0 +1,116 @@ +# LLM Wiki + +Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows. + +## Scope + +This package is the standalone home for LLM Wiki behavior. Wiki-specific routes, +UI, prompts, tools, local-folder templates, migrations, fixtures, and tests live +here rather than in Paperclip core. + +The alpha surface includes: + +- manifest-declared Wiki page, sidebar entry, and settings page +- trusted local folder declaration for `raw/`, `wiki/`, `AGENTS.md`, `IDEA.md`, `wiki/index.md`, and `wiki/log.md` +- plugin database namespace migration for wiki instances, sources, pages, operations, query sessions, and resource bindings +- managed `Wiki Maintainer` agent, managed `LLM Wiki` project, and paused managed routines for wiki update processing, lint, and index refresh +- plugin-operation issue creation using `surfaceVisibility: "plugin_operation"` +- local source capture into `raw/` with metadata rows in the plugin DB namespace +- opt-in company-scoped Paperclip event ingestion controls for issues, comments, and documents; event ingestion is disabled by default +- manual Paperclip project/root issue distillation and bounded backfill actions with explicit work items, operation issues, source caps, and estimated cost-cap refusal +- wiki page writes with plugin path validation, atomic local-folder writes, metadata/revision rows, backlink extraction, and optional stale-hash protection +- wiki tools for search/read/write/propose patch/source/log/index/backlinks workflows + +## Development + +```bash +pnpm install +pnpm dev # watch builds +pnpm dev:ui # local dev server with hot-reload events +pnpm test +``` + +From the Paperclip repo root: + +```bash +pnpm --filter @paperclipai/plugin-llm-wiki typecheck +pnpm --filter @paperclipai/plugin-llm-wiki test +pnpm --filter @paperclipai/plugin-llm-wiki build +``` + +## Alpha Verification + +Run these commands from the Paperclip repo root before handing off alpha plugin +changes: + +```bash +pnpm --filter @paperclipai/plugin-llm-wiki typecheck +pnpm --filter @paperclipai/plugin-llm-wiki test +pnpm --filter @paperclipai/plugin-llm-wiki build +``` + +The focused Vitest suite covers: + +- standalone package boundaries and package-local harness dependencies +- required local folder bootstrap writes +- raw source capture plus ingest metadata persistence +- hidden plugin-operation issue creation for ingest/query/file-as-page workflows +- disabled and enabled Paperclip event ingestion paths +- managed routine declarations, manual distill/backfill work items, cost cap refusal, and backfill project/date scoping +- atomic page writes, metadata/revision rows, backlinks, and stale-hash refusal +- query session creation, run-id recording, stream event forwarding, and completion updates +- filing a streamed query answer back into the wiki through a hidden operation + +Remaining alpha gaps: + +- Browser screenshot capture is maintained separately under `tests/screenshots` + and is not part of the cheap package verification path above. +- Host-level plugin install and live agent invocation still need Paperclip + server/runtime smoke coverage when preparing a release candidate. + + + +## Install Into Paperclip + +```bash +curl -X POST http://127.0.0.1:3100/api/plugins/install \ + -H "Content-Type: application/json" \ + -d '{"packageName":"/Users/dotta/paperclip/.paperclip/worktrees/PAP-3179-design-a-llm-wiki-plugin/packages/plugins/plugin-llm-wiki","isLocalPath":true}' +``` + +## Build Options + +- `pnpm build` uses esbuild presets from `@paperclipai/plugin-sdk/bundlers`. +- `pnpm build:rollup` uses rollup presets from the same SDK. + +## Local File Layout + +```text +/ + AGENTS.md + IDEA.md + .gitignore + raw/ + .gitkeep + wiki/ + index.md + log.md + sources/ + .gitkeep + projects/ + .gitkeep + entities/ + .gitkeep + concepts/ + .gitkeep + synthesis/ + .gitkeep +``` + +Use the settings page or `bootstrap-root` action to configure the folder and +write the starter files. The plugin uses Paperclip's local folder API for path +containment, symlink checks, read/write validation, and atomic writes. + +Bootstrap preserves existing files rather than overwriting operator edits. The +default first-install skeleton is copied from the vanilla LLM Wiki layout, with +`CLAUDE.md` renamed to `AGENTS.md`. diff --git a/packages/plugins/plugin-llm-wiki/esbuild.config.mjs b/packages/plugins/plugin-llm-wiki/esbuild.config.mjs new file mode 100644 index 00000000000..b5cfd36ed95 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/esbuild.config.mjs @@ -0,0 +1,17 @@ +import esbuild from "esbuild"; +import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers"; + +const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" }); +const watch = process.argv.includes("--watch"); + +const workerCtx = await esbuild.context(presets.esbuild.worker); +const manifestCtx = await esbuild.context(presets.esbuild.manifest); +const uiCtx = await esbuild.context(presets.esbuild.ui); + +if (watch) { + await Promise.all([workerCtx.watch(), manifestCtx.watch(), uiCtx.watch()]); + console.log("esbuild watch mode enabled for worker, manifest, and ui"); +} else { + await Promise.all([workerCtx.rebuild(), manifestCtx.rebuild(), uiCtx.rebuild()]); + await Promise.all([workerCtx.dispose(), manifestCtx.dispose(), uiCtx.dispose()]); +} diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/.gitignore b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/.gitignore new file mode 100644 index 00000000000..ef42c26de51 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/.gitignore @@ -0,0 +1,3 @@ +.DS_Store +.obsidian/workspace* +.obsidian/cache diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/AGENTS.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/AGENTS.md new file mode 100644 index 00000000000..8e740726287 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/AGENTS.md @@ -0,0 +1,123 @@ +# AGENTS.md — LLM Wiki Schema + +You are the maintainer of this personal wiki. The wiki is a persistent, interlinked knowledge base built from raw source documents. You read sources, extract knowledge, and integrate it into evolving wiki pages. The user curates sources, directs analysis, and asks questions; you handle the bookkeeping. + +The underlying pattern is described in `IDEA.md` (Karpathy's "LLM Wiki" gist). Read it if you need the philosophy; this file is the operational schema. + +## Layout + +``` +. +├── AGENTS.md # this file — your operating instructions +├── IDEA.md # the pattern this wiki follows +├── raw/ # immutable source documents (you read, never write) +└── wiki/ # generated, owned by you + ├── index.md # catalog of all pages + ├── log.md # append-only timeline of operations + ├── sources/ # one summary page per source + ├── projects/ # durable project pages, status, decisions, and history + ├── entities/ # people, organizations, products, places + ├── concepts/ # ideas, frameworks, definitions + └── synthesis/ # cross-cutting analysis, comparisons, theses +``` + +The subdirectories under `wiki/` are conventional, not enforced. Add new categories (e.g. `wiki/papers/`) as the domain demands — and update this file when you do. + +## Page conventions + +- **Filename:** kebab-case, `.md`. Treat filenames as stable; do not rename without updating backlinks. +- **Frontmatter:** YAML at the top of every wiki page. + ```yaml + --- + title: Human-readable title + type: source | project | entity | concept | synthesis + tags: [tag-a, tag-b] + sources: [raw/doc.pdf] # for source pages and synthesis pages + created: YYYY-MM-DD + updated: YYYY-MM-DD + --- + ``` +- **Cross-links:** Obsidian-style `[[wiki/entities/some-page]]` (or `[[some-page]]` when unambiguous). When you mention a concept or entity that has — or should have — its own page, link it. +- **Citations:** cite the source inline whenever a claim comes from one: `(see [[wiki/sources/some-slug]])`. +- **Voice:** terse, factual, neutral. The wiki is reference material, not narrative. + +## Operations + +### Ingest + +Triggered when the user drops a file in `raw/` and asks to process it (or just says "ingest"). + +1. Read the source end to end. +2. Briefly discuss key takeaways with the user before writing — confirm what to emphasize. +3. Create `wiki/sources/.md`: a summary page (~300–800 words) covering the source's main claims, structure, and notable quotes or data. +4. Update or create relevant pages in `entities/`, `concepts/`, `synthesis/`. A typical ingest touches 5–15 pages. +5. Add any new pages to `wiki/index.md`. +6. Append a log entry: + ``` + ## [YYYY-MM-DD] ingest | + - source: raw/ + - new pages: [[...]], [[...]] + - updated pages: [[...]], [[...]] + - notes: + ``` + +When new information contradicts an existing page, do **not** silently overwrite. Flag the contradiction on the page (a `> ⚠ contradicted by [[...]] (YYYY-MM-DD)` callout) and note it in the log. + +### Project updates + +Triggered when Paperclip project, issue, plan, comment, blocker, or status history is distilled into the wiki. + +1. Create or update `wiki/projects/.md` as the durable project overview. Keep stable sections for overview, current status, recent changes, decisions, open risks/blockers, active issues, artifacts/links, and source provenance. +2. Use `wiki/projects//decisions.md` for accepted/rejected plans, architectural decisions, approval outcomes, and reversals when a project has enough decision history to warrant a separate page. +3. Use `wiki/projects//history.md` for a compact timeline of meaningful project changes. Do not mirror every issue comment. +4. Always cite Paperclip source material by linking back to issue identifiers, document keys, and raw/source pages. Preserve `current_as_of` metadata so readers know when the project page may be stale. +5. Update `wiki/index.md` under Projects and append a `project` log entry to `wiki/log.md`. + +### Query + +The user asks a question. You: + +1. Read `wiki/index.md` to find candidate pages. +2. Read those pages; follow links as needed. +3. Answer with citations back to wiki pages, and ultimately to raw sources. +4. If the answer is substantial (a comparison, analysis, new synthesis), offer to file it under `wiki/synthesis/` so the work compounds rather than disappearing into chat history. + +If the wiki lacks what the question needs, say so plainly and suggest sources to ingest or web searches to run. + +### Lint + +On request ("lint", "health check"), scan for: + +- contradictions across pages +- claims a newer source has superseded +- orphan pages (not linked from `index.md` or any other page) +- concepts mentioned in multiple places but lacking a dedicated page +- broken `[[wiki-links]]` +- gaps where a web search or new source would help + +Report findings as a checklist and ask the user which to act on. + +## index.md format + +A catalog organized by category. Each line: `- [[path]] — one-line summary`. Keep it scannable; this is your primary navigation aid before opening pages. + +## log.md format + +Append new entries to the bottom. Every entry header follows: + +``` +## [YYYY-MM-DD] | +``` + +so `grep "^## \[" wiki/log.md | tail -10` always returns recent activity. Operations: `ingest`, `query`, `lint`, `setup`, `refactor`. + +## Customization + +This schema is intentionally generic. As the wiki's domain becomes clear, evolve it: + +- add domain-specific page types and subdirectories +- adjust frontmatter fields +- specify preferred output formats for queries (Marp slides, charts, tables) +- record workflow preferences (one-at-a-time vs batch ingest, level of human supervision) + +When you and the user agree on a convention, **write it into this file**. The schema is the wiki's source of truth for how the wiki is built. diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/IDEA.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/IDEA.md new file mode 100644 index 00000000000..35ef0712904 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/IDEA.md @@ -0,0 +1,75 @@ +# LLM Wiki + +A pattern for building personal knowledge bases using LLMs. + +This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you. + +## The core idea + +Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way. + +The idea here is different. Instead of just retrieving from raw documents at query time, the LLM **incrementally builds and maintains a persistent wiki** — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then *kept current*, not re-derived on every query. + +This is the key difference: **the wiki is a persistent, compounding artifact.** The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask. + +You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase. + +This can apply to a lot of different contexts. A few examples: + +- **Personal**: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time. +- **Research**: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis. +- **Reading a book**: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like [Tolkien Gateway](https://tolkiengateway.net/wiki/Main_Page) — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance. +- **Business/team**: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do. +- **Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives** — anything where you're accumulating knowledge over time and want it organized rather than scattered. + +## Architecture + +There are three layers: + +**Raw sources** — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth. + +**The wiki** — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it. + +**The schema** — a document (e.g. AGENTS.md for Paperclip agents) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain. + +## Operations + +**Ingest.** You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions. + +**Query.** You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: **good answers can be filed back into the wiki as new pages.** A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do. + +**Lint.** Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows. + +## Indexing and logging + +Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes: + +**index.md** is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure. + +**log.md** is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. `## [2026-04-02] ingest | Article Title`), the log becomes parseable with simple unix tools — `grep "^## \[" log.md | tail -5` gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently. + +## Optional: CLI tools + +At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. [qmd](https://github.com/tobi/qmd) is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises. + +## Tips and tricks + +- **Obsidian Web Clipper** is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection. +- **Download images locally.** In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. `raw/assets/`). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough. +- **Obsidian's graph view** is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans. +- **Marp** is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content. +- **Dataview** is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists. +- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free. + +## Why this works + +The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero. + +The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else. + +The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that. + + +## Note + +This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest. diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/plugin-boundaries.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/plugin-boundaries.md new file mode 100644 index 00000000000..89d8a8d9840 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/plugin-boundaries.md @@ -0,0 +1,3 @@ +# Raw Source + +LLM Wiki code must live in the standalone plugin package. diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/areas/knowledge.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/areas/knowledge.md new file mode 100644 index 00000000000..46462345bfe --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/areas/knowledge.md @@ -0,0 +1,3 @@ +# Knowledge + +The wiki stores durable knowledge as local markdown files. diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/plugin-boundaries.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/plugin-boundaries.md new file mode 100644 index 00000000000..595ee78cf19 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/plugin-boundaries.md @@ -0,0 +1,3 @@ +# Plugin Boundaries + +LLM Wiki routes, prompts, UI, tools, and migrations belong inside the plugin. diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/entities/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/entities/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/index.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/index.md new file mode 100644 index 00000000000..58ad0a5d08f --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/index.md @@ -0,0 +1,23 @@ +# Index + +Catalog of all wiki pages. Updated on every ingest. + +## Sources + +_(none yet)_ + +## Projects + +_(none yet)_ + +## Entities + +_(none yet)_ + +## Concepts + +_(none yet)_ + +## Synthesis + +_(none yet)_ diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/log.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/log.md new file mode 100644 index 00000000000..49bf864d401 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/log.md @@ -0,0 +1,9 @@ +# Log + +Append-only chronological record of wiki operations. + +## [2026-05-03] setup | wiki initialized +- created `AGENTS.md` (schema) +- created `wiki/` skeleton: `index.md`, `log.md`, `sources/`, `entities/`, `concepts/`, `synthesis/` +- created `raw/` for source documents +- pattern reference: `IDEA.md` (Karpathy "LLM Wiki" gist, https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/projects/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/projects/.gitkeep new file mode 100644 index 00000000000..8b137891791 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/projects/.gitkeep @@ -0,0 +1 @@ + diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/sources/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/sources/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/synthesis/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/synthesis/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/packages/plugins/plugin-llm-wiki/migrations/001_llm_wiki.sql b/packages/plugins/plugin-llm-wiki/migrations/001_llm_wiki.sql new file mode 100644 index 00000000000..01d5067cdcf --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/migrations/001_llm_wiki.sql @@ -0,0 +1,101 @@ +CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_instances ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + root_folder_key text NOT NULL DEFAULT 'wiki-root', + configured_root_path text, + schema_version integer NOT NULL DEFAULT 1, + settings jsonb NOT NULL DEFAULT '{}'::jsonb, + managed_agent_key text, + managed_project_key text, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE (company_id, wiki_id) +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_sources ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + source_type text NOT NULL, + title text, + url text, + raw_path text NOT NULL, + content_hash text NOT NULL, + status text NOT NULL DEFAULT 'captured', + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_pages ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + path text NOT NULL, + title text, + page_type text, + frontmatter jsonb NOT NULL DEFAULT '{}'::jsonb, + source_refs jsonb NOT NULL DEFAULT '[]'::jsonb, + backlinks jsonb NOT NULL DEFAULT '[]'::jsonb, + content_hash text, + current_revision_id uuid, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE (company_id, wiki_id, path) +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + page_id uuid REFERENCES plugin_llm_wiki_8f50da974f.wiki_pages(id) ON DELETE CASCADE, + operation_id uuid, + path text NOT NULL, + content_hash text NOT NULL, + summary text, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_operations ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + operation_type text NOT NULL, + status text NOT NULL, + hidden_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL, + project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL, + run_ids jsonb NOT NULL DEFAULT '[]'::jsonb, + cost_cents integer NOT NULL DEFAULT 0, + warnings jsonb NOT NULL DEFAULT '[]'::jsonb, + affected_pages jsonb NOT NULL DEFAULT '[]'::jsonb, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + hidden_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL, + agent_session_id text, + status text NOT NULL DEFAULT 'active', + filed_outputs jsonb NOT NULL DEFAULT '[]'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_resource_bindings ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + resource_kind text NOT NULL, + resource_key text NOT NULL, + resolved_id uuid, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE (company_id, wiki_id, resource_kind, resource_key) +); diff --git a/packages/plugins/plugin-llm-wiki/migrations/002_paperclip_distillation.sql b/packages/plugins/plugin-llm-wiki/migrations/002_paperclip_distillation.sql new file mode 100644 index 00000000000..aa8c269bb59 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/migrations/002_paperclip_distillation.sql @@ -0,0 +1,88 @@ +CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + source_scope text NOT NULL, + scope_key text NOT NULL, + project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE, + root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE, + source_kind text NOT NULL DEFAULT 'paperclip_issue_history', + last_processed_at timestamptz, + last_observed_at timestamptz, + pending_event_count integer NOT NULL DEFAULT 0, + last_successful_run_id uuid, + last_source_hash text, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE (company_id, wiki_id, source_scope, scope_key, source_kind) +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + work_item_kind text NOT NULL, + status text NOT NULL DEFAULT 'pending', + priority text NOT NULL DEFAULT 'medium', + project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE, + root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE, + requested_by_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL, + idempotency_key text, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE (company_id, wiki_id, idempotency_key) +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + cursor_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors(id) ON DELETE SET NULL, + work_item_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items(id) ON DELETE SET NULL, + project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL, + root_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL, + source_window_start timestamptz, + source_window_end timestamptz, + source_hash text, + status text NOT NULL, + operation_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL, + retry_count integer NOT NULL DEFAULT 0, + cost_cents integer NOT NULL DEFAULT 0, + warnings jsonb NOT NULL DEFAULT '[]'::jsonb, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + distillation_run_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_runs(id) ON DELETE CASCADE, + project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL, + root_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL, + source_hash text NOT NULL, + max_characters integer NOT NULL, + clipped boolean NOT NULL DEFAULT false, + source_refs jsonb NOT NULL DEFAULT '[]'::jsonb, + bundle_markdown text NOT NULL, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings ( + id uuid PRIMARY KEY, + company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE, + wiki_id text NOT NULL, + project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE, + root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE, + page_path text NOT NULL, + last_applied_source_hash text, + last_distillation_run_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_runs(id) ON DELETE SET NULL, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE (company_id, wiki_id, page_path) +); diff --git a/packages/plugins/plugin-llm-wiki/package.json b/packages/plugins/plugin-llm-wiki/package.json new file mode 100644 index 00000000000..4461c84527c --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/package.json @@ -0,0 +1,47 @@ +{ + "name": "@paperclipai/plugin-llm-wiki", + "version": "0.1.0", + "type": "module", + "private": true, + "description": "Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.", + "scripts": { + "prebuild": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps", + "build": "node ./esbuild.config.mjs", + "build:rollup": "rollup -c", + "dev": "node ./esbuild.config.mjs --watch", + "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177", + "test": "vitest run --config ./vitest.config.ts", + "typecheck": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && tsc --noEmit" + }, + "paperclipPlugin": { + "manifest": "./dist/manifest.js", + "worker": "./dist/worker.js", + "ui": "./dist/ui/" + }, + "keywords": [ + "paperclip", + "plugin", + "automation", + "wiki", + "knowledge" + ], + "author": "Paperclip", + "license": "MIT", + "devDependencies": { + "@paperclipai/plugin-sdk": "workspace:*", + "@rollup/plugin-node-resolve": "^16.0.1", + "@rollup/plugin-typescript": "^12.1.2", + "@types/node": "^24.6.0", + "@types/react": "^19.0.8", + "@types/react-dom": "^19.0.3", + "esbuild": "^0.27.3", + "react-dom": "^19.0.0", + "rollup": "^4.38.0", + "tslib": "^2.8.1", + "typescript": "^5.7.3", + "vitest": "^3.0.5" + }, + "peerDependencies": { + "react": ">=18" + } +} diff --git a/packages/plugins/plugin-llm-wiki/prompts/backfill.md b/packages/plugins/plugin-llm-wiki/prompts/backfill.md new file mode 100644 index 00000000000..45f56d4e4a3 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/backfill.md @@ -0,0 +1,22 @@ +# Paperclip Wiki Backfill + +Backfill a historical Paperclip project or root issue into the LLM Wiki. + +Return structured JSON with: + +- `project_page` +- optional `decisions_page` +- optional `history_page` +- `source_hash` +- `source_refs` +- `cursor_window` +- `warnings` +- `human_review_required` + +Rules: + +- Summarize historical issue history into durable project knowledge. +- Do not create one page per issue by default. +- Prefer timeline entries for meaningful state transitions, decisions, and completed work. +- Include clipped-source warnings and source provenance. +- Use proposed patches first; only write pages when auto-apply policy allows it and hashes still match. diff --git a/packages/plugins/plugin-llm-wiki/prompts/decision-distill.md b/packages/plugins/plugin-llm-wiki/prompts/decision-distill.md new file mode 100644 index 00000000000..4d07fd25819 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/decision-distill.md @@ -0,0 +1,19 @@ +# Paperclip Decision Distillation + +Extract durable project decisions from Paperclip issue history. + +Return structured JSON with: + +- `page_path`: `wiki/projects//decisions.md` +- `operation_type`: `decision_distill` +- `decisions`: accepted, rejected, reversed, or superseded decisions +- `source_refs` +- `warnings` +- `human_review_required` + +Rules: + +- A decision needs explicit evidence: accepted plan, approval outcome, maintainer comment, merged implementation, or reversal. +- Preserve who/what/when/source, but do not invent a decision owner. +- Distinguish "proposal" from "accepted decision". +- Mark ambiguous or conflicting material for human review. diff --git a/packages/plugins/plugin-llm-wiki/prompts/ingest.md b/packages/plugins/plugin-llm-wiki/prompts/ingest.md new file mode 100644 index 00000000000..15b41c38101 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/ingest.md @@ -0,0 +1,6 @@ +# Ingest Prompt + +You are ingesting source material into a local LLM Wiki. + +Read WIKI.md, inspect the current index, summarize the source, propose page +updates, and preserve provenance links back to raw/. diff --git a/packages/plugins/plugin-llm-wiki/prompts/lint.md b/packages/plugins/plugin-llm-wiki/prompts/lint.md new file mode 100644 index 00000000000..cf4b053ae14 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/lint.md @@ -0,0 +1,6 @@ +# Lint Prompt + +Lint the LLM Wiki for contradictions, stale claims, orphan pages, missing +backlinks, weak provenance, and index/log drift. + +Return findings with concrete file paths and suggested fixes. diff --git a/packages/plugins/plugin-llm-wiki/prompts/paperclip-source-bundle.md b/packages/plugins/plugin-llm-wiki/prompts/paperclip-source-bundle.md new file mode 100644 index 00000000000..61beaa983bb --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/paperclip-source-bundle.md @@ -0,0 +1,20 @@ +# Paperclip Source Bundle Reader + +You are reading a bounded Paperclip issue-history source bundle for the LLM Wiki. + +Return structured JSON that can be validated before any wiki write: + +- `source_hash`: the bundle hash supplied by the tool +- `cursor_window`: `{ "start": string | null, "end": string | null }` +- `source_refs`: the issue, comment, and document refs used for every claim +- `signals`: durable changes worth distilling, grouped by status, decision, risk, artifact, and implementation note +- `warnings`: clipped sources, contradictions, missing context, stale hashes, or low-confidence material +- `low_signal`: true when the bundle contains no durable project change + +Rules: + +- Preserve Paperclip issue identifiers and document keys exactly. +- Treat issue/comment/document history as provenance, not as prose to copy wholesale. +- Ignore plugin-operation issues and raw heartbeat noise. +- Do not infer live status beyond the bundle's `current_as_of` timestamp. +- Prefer concise, source-cited observations over narrative. diff --git a/packages/plugins/plugin-llm-wiki/prompts/project-page-distill.md b/packages/plugins/plugin-llm-wiki/prompts/project-page-distill.md new file mode 100644 index 00000000000..b350685f8bd --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/project-page-distill.md @@ -0,0 +1,35 @@ +# Paperclip Project Page Distillation + +Update `wiki/projects/.md` from a Paperclip source bundle. + +Return structured JSON with: + +- `page_path` +- `operation_type`: `project_page_distill` +- `current_hash` +- `proposed_markdown` +- `source_hash` +- `source_refs` +- `cursor_window` +- `confidence`: `high`, `medium`, or `low` +- `warnings` +- `human_review_required` + +The page must keep these stable sections: + +1. Overview +2. Current Status +3. Recent Changes +4. Decisions +5. Open Risks / Blockers +6. Active Issues +7. Artifacts / Links +8. Source Provenance + +Rules: + +- Cite Paperclip source refs in the relevant section and again in Source Provenance. +- Show "Current as of" near the top. +- Keep live-state language conservative when the cursor window is old or clipped. +- Do not remove existing durable context unless a source ref supersedes it. +- Set `human_review_required` when hashes are stale, sources are clipped, contradictions appear, or confidence is low. diff --git a/packages/plugins/plugin-llm-wiki/prompts/query.md b/packages/plugins/plugin-llm-wiki/prompts/query.md new file mode 100644 index 00000000000..4b8c8e51c4f --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/query.md @@ -0,0 +1,6 @@ +# Query Prompt + +Answer from the LLM Wiki. + +Read index.md first, inspect relevant pages and raw/source references, cite the +pages used, and say when the wiki does not contain enough evidence. diff --git a/packages/plugins/plugin-llm-wiki/prompts/status-refresh.md b/packages/plugins/plugin-llm-wiki/prompts/status-refresh.md new file mode 100644 index 00000000000..4222df049b3 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/prompts/status-refresh.md @@ -0,0 +1,28 @@ +# Paperclip Status Refresh + +Refresh only the status-sensitive sections of an existing project page: + +- Current Status +- Recent Changes +- Open Risks / Blockers +- Active Issues +- Source Provenance + +Return structured JSON with: + +- `page_path` +- `operation_type`: `status_refresh` +- `current_hash` +- `proposed_markdown` +- `source_hash` +- `source_refs` +- `cursor_window` +- `warnings` +- `human_review_required` + +Rules: + +- Preserve stable overview and decision text unless the bundle explicitly supersedes it. +- Use source refs for every status change. +- Refuse stale hashes instead of overwriting. +- Set review required when the source window is clipped or inconsistent. diff --git a/packages/plugins/plugin-llm-wiki/rollup.config.mjs b/packages/plugins/plugin-llm-wiki/rollup.config.mjs new file mode 100644 index 00000000000..ccee40a7443 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/rollup.config.mjs @@ -0,0 +1,28 @@ +import { nodeResolve } from "@rollup/plugin-node-resolve"; +import typescript from "@rollup/plugin-typescript"; +import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers"; + +const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" }); + +function withPlugins(config) { + if (!config) return null; + return { + ...config, + plugins: [ + nodeResolve({ + extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"], + }), + typescript({ + tsconfig: "./tsconfig.json", + declaration: false, + declarationMap: false, + }), + ], + }; +} + +export default [ + withPlugins(presets.rollup.manifest), + withPlugins(presets.rollup.worker), + withPlugins(presets.rollup.ui), +].filter(Boolean); diff --git a/packages/plugins/plugin-llm-wiki/screenshots/01-wiki-browse.png b/packages/plugins/plugin-llm-wiki/screenshots/01-wiki-browse.png new file mode 100644 index 00000000000..19632fdcab2 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/01-wiki-browse.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/02-wiki-ingest.png b/packages/plugins/plugin-llm-wiki/screenshots/02-wiki-ingest.png new file mode 100644 index 00000000000..fad8e4e58f4 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/02-wiki-ingest.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/03-wiki-query.png b/packages/plugins/plugin-llm-wiki/screenshots/03-wiki-query.png new file mode 100644 index 00000000000..a6355906987 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/03-wiki-query.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/04-wiki-lint.png b/packages/plugins/plugin-llm-wiki/screenshots/04-wiki-lint.png new file mode 100644 index 00000000000..9c9f084c739 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/04-wiki-lint.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/05-wiki-history.png b/packages/plugins/plugin-llm-wiki/screenshots/05-wiki-history.png new file mode 100644 index 00000000000..082f23bbf1c Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/05-wiki-history.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/06-wiki-settings.png b/packages/plugins/plugin-llm-wiki/screenshots/06-wiki-settings.png new file mode 100644 index 00000000000..1198b9cf818 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/06-wiki-settings.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/07-host-settings.png b/packages/plugins/plugin-llm-wiki/screenshots/07-host-settings.png new file mode 100644 index 00000000000..fed5a0e88f5 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/07-host-settings.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/09-sidebar-link.png b/packages/plugins/plugin-llm-wiki/screenshots/09-sidebar-link.png new file mode 100644 index 00000000000..d24ebcb0011 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/09-sidebar-link.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/11-wiki-distillation-settings.png b/packages/plugins/plugin-llm-wiki/screenshots/11-wiki-distillation-settings.png new file mode 100644 index 00000000000..a3d87fb599b Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/11-wiki-distillation-settings.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/12-wiki-distillation-unconfigured.png b/packages/plugins/plugin-llm-wiki/screenshots/12-wiki-distillation-unconfigured.png new file mode 100644 index 00000000000..2f281abd9eb Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/12-wiki-distillation-unconfigured.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/01-wiki-browse.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/01-wiki-browse.png new file mode 100644 index 00000000000..08b4cb04fd1 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/01-wiki-browse.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/02-wiki-ingest.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/02-wiki-ingest.png new file mode 100644 index 00000000000..633adaad074 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/02-wiki-ingest.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/03-wiki-query.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/03-wiki-query.png new file mode 100644 index 00000000000..8d82f7ea31f Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/03-wiki-query.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/04-wiki-lint.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/04-wiki-lint.png new file mode 100644 index 00000000000..0757fe9b1f6 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/04-wiki-lint.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/05-wiki-history.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/05-wiki-history.png new file mode 100644 index 00000000000..7675c6becb1 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/05-wiki-history.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/06-wiki-settings.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/06-wiki-settings.png new file mode 100644 index 00000000000..d9641eb057d Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/06-wiki-settings.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/07-host-settings.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/07-host-settings.png new file mode 100644 index 00000000000..d9641eb057d Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/07-host-settings.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/09-sidebar-link.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/09-sidebar-link.png new file mode 100644 index 00000000000..b857e857e4c Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/09-sidebar-link.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/11-wiki-distillation-settings.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/11-wiki-distillation-settings.png new file mode 100644 index 00000000000..2016ac94867 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/11-wiki-distillation-settings.png differ diff --git a/packages/plugins/plugin-llm-wiki/screenshots/mobile/12-wiki-distillation-unconfigured.png b/packages/plugins/plugin-llm-wiki/screenshots/mobile/12-wiki-distillation-unconfigured.png new file mode 100644 index 00000000000..58b993fb5a9 Binary files /dev/null and b/packages/plugins/plugin-llm-wiki/screenshots/mobile/12-wiki-distillation-unconfigured.png differ diff --git a/packages/plugins/plugin-llm-wiki/src/manifest.ts b/packages/plugins/plugin-llm-wiki/src/manifest.ts new file mode 100644 index 00000000000..6c40683cbb0 --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/src/manifest.ts @@ -0,0 +1,502 @@ +import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk"; +import { DEFAULT_AGENT_INSTRUCTIONS } from "./templates.js"; + +export const PLUGIN_ID = "paperclipai.plugin-llm-wiki"; +export const WIKI_ROOT_FOLDER_KEY = "wiki-root"; +export const WIKI_MAINTAINER_AGENT_KEY = "wiki-maintainer"; +export const WIKI_PROJECT_KEY = "llm-wiki"; +export const CURSOR_WINDOW_ROUTINE_KEY = "cursor-window-processing"; +export const NIGHTLY_LINT_ROUTINE_KEY = "nightly-wiki-lint"; +export const INDEX_REFRESH_ROUTINE_KEY = "index-refresh"; +export const DEFAULT_MAX_SOURCE_BYTES = 250000; +export const DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS = 12000; +export const DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS = 60000; +export const DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_CHARS = 120000; +export const DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_COST_CENTS = 100; +export const DEFAULT_PAPERCLIP_COST_CENTS_PER_1K_CHARS = 1; +export const WIKI_MAINTENANCE_ROUTINE_KEYS = [ + CURSOR_WINDOW_ROUTINE_KEY, + NIGHTLY_LINT_ROUTINE_KEY, + INDEX_REFRESH_ROUTINE_KEY, +] as const; + +const manifest: PaperclipPluginManifestV1 = { + id: PLUGIN_ID, + apiVersion: 1, + version: "0.1.0", + displayName: "LLM Wiki", + description: "Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.", + author: "Paperclip", + categories: ["automation", "ui"], + capabilities: [ + "events.subscribe", + "jobs.schedule", + "api.routes.register", + "database.namespace.migrate", + "database.namespace.read", + "database.namespace.write", + "companies.read", + "projects.read", + "projects.managed", + "issues.read", + "issue.subtree.read", + "issues.create", + "issues.update", + "issues.wakeup", + "issues.orchestration.read", + "issue.comments.read", + "issue.comments.create", + "issue.documents.read", + "issue.documents.write", + "agents.read", + "agents.managed", + "agent.sessions.create", + "agent.sessions.list", + "agent.sessions.send", + "agent.sessions.close", + "routines.managed", + "local.folders", + "agent.tools.register", + "metrics.write", + "activity.log.write", + "plugin.state.read", + "plugin.state.write", + "ui.sidebar.register", + "ui.page.register", + "instance.settings.register" + ], + instanceConfigSchema: { + type: "object", + properties: { + autoApplyIngestPatches: { + type: "boolean", + title: "Auto-apply ingest patches", + default: false, + description: "Allow ingest operations to apply generated wiki changes without a manual accept step. Ignored in authenticated/public deployments, which always require manual review before wiki writes." + }, + maxSourceBytes: { + type: "number", + title: "Maximum source size", + default: DEFAULT_MAX_SOURCE_BYTES, + description: "Maximum bytes accepted for pasted or fetched source content." + }, + maxPaperclipIssueSourceCharacters: { + type: "number", + title: "Maximum Paperclip source characters per issue", + default: DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS, + description: "Maximum characters included from one Paperclip issue, comment, or document during distillation." + }, + maxPaperclipCursorWindowCharacters: { + type: "number", + title: "Maximum Paperclip cursor window characters", + default: DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS, + description: "Maximum characters included in one cursor-window distillation bundle." + }, + maxPaperclipRoutineRunCharacters: { + type: "number", + title: "Maximum Paperclip routine run characters", + default: DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_CHARS, + description: "Maximum source characters processed by one managed distillation routine run." + }, + maxPaperclipRoutineRunCostCents: { + type: "number", + title: "Maximum Paperclip routine run cost", + default: DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_COST_CENTS, + description: "Estimated cost cap in cents for one Paperclip distillation run. Runs are refused before page generation when the estimate exceeds this cap." + }, + paperclipCostCentsPerThousandSourceCharacters: { + type: "number", + title: "Paperclip source cost estimate", + default: DEFAULT_PAPERCLIP_COST_CENTS_PER_1K_CHARS, + description: "Conservative cost estimate used to stop Paperclip distillation before runaway token spend." + } + } + }, + entrypoints: { + worker: "./dist/worker.js", + ui: "./dist/ui" + }, + database: { + namespaceSlug: "llm_wiki", + migrationsDir: "migrations", + coreReadTables: ["companies", "issues", "projects", "agents"] + }, + localFolders: [ + { + folderKey: WIKI_ROOT_FOLDER_KEY, + displayName: "Wiki root", + description: "Company-scoped local folder that stores raw sources, wiki pages, AGENTS.md, IDEA.md, wiki/index.md, and wiki/log.md.", + access: "readWrite", + requiredDirectories: [ + "raw", + "wiki", + "wiki/sources", + "wiki/projects", + "wiki/entities", + "wiki/concepts", + "wiki/synthesis" + ], + requiredFiles: ["AGENTS.md", "IDEA.md", "wiki/index.md", "wiki/log.md"] + } + ], + agents: [ + { + agentKey: WIKI_MAINTAINER_AGENT_KEY, + displayName: "Wiki Maintainer", + role: "knowledge-maintainer", + title: "LLM Wiki Maintainer", + icon: "book-open", + capabilities: "Ingests source material, maintains local wiki pages, answers cited questions, and runs wiki lint/maintenance through plugin tools.", + adapterType: "claude_local", + adapterPreference: ["claude_local", "codex_local", "gemini_local", "opencode_local", "cursor", "pi_local"], + adapterConfig: {}, + runtimeConfig: { + modelProfiles: { + cheap: { + purpose: "classification, lint planning, index maintenance" + } + } + }, + permissions: { + pluginTools: [PLUGIN_ID] + }, + status: "paused", + budgetMonthlyCents: 0, + instructions: { + entryFile: "AGENTS.md", + content: DEFAULT_AGENT_INSTRUCTIONS + } + } + ], + projects: [ + { + projectKey: WIKI_PROJECT_KEY, + displayName: "LLM Wiki", + description: "Plugin-managed inspection area for LLM Wiki ingest, query, lint, and maintenance operation issues.", + status: "in_progress", + color: "#2563eb" + } + ], + routines: [ + { + routineKey: CURSOR_WINDOW_ROUTINE_KEY, + title: "Process LLM Wiki updates", + description: "Scheduled Paperclip issue-history distillation that processes bounded cursor windows, retries, and selected backfill work into project wiki patches.", + status: "paused", + priority: "low", + assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY }, + projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY }, + concurrencyPolicy: "skip_if_active", + catchUpPolicy: "skip_missed", + triggers: [ + { + kind: "schedule", + label: "Every 6 hours", + enabled: false, + cronExpression: "0 */6 * * *", + timezone: "UTC", + signingMode: null, + replayWindowSec: null + } + ], + issueTemplate: { + surfaceVisibility: "plugin_operation", + originId: "routine:cursor-window-processing", + billingCode: "plugin-llm-wiki:distillation" + } + }, + { + routineKey: NIGHTLY_LINT_ROUTINE_KEY, + title: "Run LLM Wiki lint", + description: "Scheduled wiki maintenance that checks index/log drift, orphan pages, missing backlinks, and stale source provenance.", + status: "paused", + priority: "low", + assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY }, + projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY }, + concurrencyPolicy: "skip_if_active", + catchUpPolicy: "skip_missed", + triggers: [ + { + kind: "schedule", + label: "Nightly", + enabled: false, + cronExpression: "0 3 * * *", + timezone: "UTC", + signingMode: null, + replayWindowSec: null + } + ], + issueTemplate: { + surfaceVisibility: "plugin_operation", + originId: "routine:nightly-wiki-lint", + billingCode: "plugin-llm-wiki:maintenance" + } + }, + { + routineKey: INDEX_REFRESH_ROUTINE_KEY, + title: "Refresh LLM Wiki index", + description: "Scheduled wiki maintenance that refreshes wiki/index.md, updates wiki/log.md, and checks that recently changed pages are linked from the index.", + status: "paused", + priority: "low", + assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY }, + projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY }, + concurrencyPolicy: "skip_if_active", + catchUpPolicy: "skip_missed", + triggers: [ + { + kind: "schedule", + label: "Hourly", + enabled: false, + cronExpression: "0 * * * *", + timezone: "UTC", + signingMode: null, + replayWindowSec: null + } + ], + issueTemplate: { + surfaceVisibility: "plugin_operation", + originId: "routine:index-refresh", + billingCode: "plugin-llm-wiki:maintenance" + } + } + ], + jobs: [ + { + jobKey: "folder-health-check", + displayName: "Wiki folder health check", + description: "Records lightweight health metadata for configured wiki roots.", + schedule: "0 * * * *" + } + ], + tools: [ + { + name: "wiki_search", + displayName: "Search Wiki", + description: "Search indexed wiki page and source metadata.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + query: { type: "string" }, + limit: { type: "number" } + }, + required: ["companyId", "wikiId", "query"] + } + }, + { + name: "wiki_read_page", + displayName: "Read Wiki Page", + description: "Read a markdown wiki page from the configured local wiki root.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + path: { type: "string" } + }, + required: ["companyId", "wikiId", "path"] + } + }, + { + name: "wiki_write_page", + displayName: "Write Wiki Page", + description: "Atomically write a markdown wiki page after plugin path validation and optional hash conflict checks. Protected control files such as AGENTS.md and IDEA.md are excluded from agent-tool writes.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + path: { type: "string" }, + contents: { type: "string" }, + expectedHash: { type: "string" }, + summary: { type: "string" } + }, + required: ["companyId", "wikiId", "path", "contents"] + } + }, + { + name: "wiki_propose_patch", + displayName: "Propose Wiki Patch", + description: "Return a structured proposed page write without changing files.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + path: { type: "string" }, + contents: { type: "string" }, + summary: { type: "string" } + }, + required: ["companyId", "wikiId", "path", "contents"] + } + }, + { + name: "wiki_list_sources", + displayName: "List Wiki Sources", + description: "Return captured raw source metadata from the plugin index.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + limit: { type: "number" } + }, + required: ["companyId", "wikiId"] + } + }, + { + name: "wiki_read_source", + displayName: "Read Wiki Source", + description: "Read a captured raw source from the configured local wiki root.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + rawPath: { type: "string" } + }, + required: ["companyId", "wikiId", "rawPath"] + } + }, + { + name: "wiki_append_log", + displayName: "Append Wiki Log", + description: "Append a maintenance note to wiki/log.md.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + entry: { type: "string" } + }, + required: ["companyId", "wikiId", "entry"] + } + }, + { + name: "wiki_update_index", + displayName: "Update Wiki Index", + description: "Atomically replace wiki/index.md with optional hash conflict checks.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + contents: { type: "string" }, + expectedHash: { type: "string" } + }, + required: ["companyId", "wikiId", "contents"] + } + }, + { + name: "wiki_list_backlinks", + displayName: "List Wiki Backlinks", + description: "Return indexed backlinks for a wiki page.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" }, + path: { type: "string" } + }, + required: ["companyId", "wikiId", "path"] + } + }, + { + name: "wiki_list_pages", + displayName: "List Wiki Pages", + description: "Return the known page index from plugin metadata.", + parametersSchema: { + type: "object", + properties: { + companyId: { type: "string" }, + wikiId: { type: "string" } + }, + required: ["companyId", "wikiId"] + } + } + ], + apiRoutes: [ + { + routeKey: "overview", + method: "GET", + path: "/overview", + auth: "board-or-agent", + capability: "api.routes.register", + companyResolution: { from: "query", key: "companyId" } + }, + { + routeKey: "bootstrap", + method: "POST", + path: "/bootstrap", + auth: "board", + capability: "api.routes.register", + companyResolution: { from: "body", key: "companyId" } + }, + { + routeKey: "capture-source", + method: "POST", + path: "/sources", + auth: "board-or-agent", + capability: "api.routes.register", + companyResolution: { from: "body", key: "companyId" } + }, + { + routeKey: "operations", + method: "GET", + path: "/operations", + auth: "board-or-agent", + capability: "api.routes.register", + companyResolution: { from: "query", key: "companyId" } + }, + { + routeKey: "start-query", + method: "POST", + path: "/query-sessions", + auth: "board", + capability: "api.routes.register", + companyResolution: { from: "body", key: "companyId" } + }, + { + routeKey: "file-as-page", + method: "POST", + path: "/file-as-page", + auth: "board", + capability: "api.routes.register", + companyResolution: { from: "body", key: "companyId" } + } + ], + ui: { + slots: [ + { + type: "sidebar", + id: "wiki-sidebar", + displayName: "Wiki", + exportName: "SidebarLink", + order: 35 + }, + { + type: "page", + id: "wiki-page", + displayName: "Wiki", + exportName: "WikiPage", + routePath: "wiki" + }, + { + type: "routeSidebar", + id: "wiki-route-sidebar", + displayName: "Wiki", + exportName: "WikiRouteSidebar", + routePath: "wiki" + }, + { + type: "settingsPage", + id: "settings", + displayName: "LLM Wiki", + exportName: "SettingsPage" + } + ] + } +}; + +export default manifest; diff --git a/packages/plugins/plugin-llm-wiki/src/templates.ts b/packages/plugins/plugin-llm-wiki/src/templates.ts new file mode 100644 index 00000000000..d22917c8f5f --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/src/templates.ts @@ -0,0 +1,63 @@ +import { readFileSync } from "node:fs"; + +export const REQUIRED_WIKI_DIRECTORIES = [ + "raw", + "wiki", + "wiki/sources", + "wiki/projects", + "wiki/entities", + "wiki/concepts", + "wiki/synthesis", +] as const; + +export const REQUIRED_WIKI_FILES = ["AGENTS.md", "IDEA.md", "wiki/index.md", "wiki/log.md"] as const; +export const KARPATHY_LLM_WIKI_GIST_URL = "https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f"; + +function templateFile(path: string): string { + return readFileSync(new URL(`../templates/${path}`, import.meta.url), "utf8"); +} + +function promptFile(path: string): string { + return readFileSync(new URL(`../prompts/${path}`, import.meta.url), "utf8"); +} + +export const DEFAULT_WIKI_SCHEMA = templateFile("AGENTS.md"); +export const DEFAULT_AGENT_INSTRUCTIONS = templateFile("WIKI_MAINTAINER_AGENT.md"); +export const DEFAULT_IDEA = templateFile("IDEA.md"); +export const DEFAULT_INDEX = templateFile("wiki/index.md"); +export const DEFAULT_LOG = templateFile("wiki/log.md"); +export const DEFAULT_GITIGNORE = templateFile(".gitignore"); +export const PAPERCLIP_SOURCE_BUNDLE_PROMPT = promptFile("paperclip-source-bundle.md"); +export const PROJECT_PAGE_DISTILL_PROMPT = promptFile("project-page-distill.md"); +export const DECISION_DISTILL_PROMPT = promptFile("decision-distill.md"); +export const STATUS_REFRESH_PROMPT = promptFile("status-refresh.md"); +export const BACKFILL_PROMPT = promptFile("backfill.md"); + +export const INGEST_PROMPT = `You are ingesting source material into a local LLM Wiki. + +Follow AGENTS.md. Read IDEA.md if you need the pattern background. Read wiki/index.md and recent wiki/log.md entries, read the raw source, summarize durable knowledge, update or propose focused wiki pages, keep provenance links back to raw/, refresh wiki/index.md, and append wiki/log.md. +`; + +export const QUERY_PROMPT = `Answer from the LLM Wiki. + +Read wiki/index.md first, inspect relevant pages and raw/source references, cite the wiki page paths and raw source paths used, and say when the wiki does not contain enough evidence. Useful durable synthesis should be filed back into wiki/. +`; + +export const LINT_PROMPT = `Lint the LLM Wiki for contradictions, stale claims, orphan pages, missing backlinks, weak provenance, and wiki/index.md / wiki/log.md drift. + +Also look for important concepts mentioned without pages and answers that should have been filed back into wiki/. Return findings with severity, concrete file paths, evidence, and suggested fixes. +`; + +export const BOOTSTRAP_FILES: ReadonlyArray<{ path: string; contents: string }> = [ + { path: ".gitignore", contents: DEFAULT_GITIGNORE }, + { path: "AGENTS.md", contents: DEFAULT_WIKI_SCHEMA }, + { path: "IDEA.md", contents: DEFAULT_IDEA }, + { path: "wiki/index.md", contents: DEFAULT_INDEX }, + { path: "wiki/log.md", contents: DEFAULT_LOG }, + { path: "raw/.gitkeep", contents: "" }, + { path: "wiki/sources/.gitkeep", contents: "" }, + { path: "wiki/projects/.gitkeep", contents: "" }, + { path: "wiki/entities/.gitkeep", contents: "" }, + { path: "wiki/concepts/.gitkeep", contents: "" }, + { path: "wiki/synthesis/.gitkeep", contents: "" }, +]; diff --git a/packages/plugins/plugin-llm-wiki/src/ui/index.tsx b/packages/plugins/plugin-llm-wiki/src/ui/index.tsx new file mode 100644 index 00000000000..5d6918f7c8c --- /dev/null +++ b/packages/plugins/plugin-llm-wiki/src/ui/index.tsx @@ -0,0 +1,4939 @@ +import { + AssigneePicker, + FileTree, + ManagedRoutinesList as PluginManagedRoutinesList, + MarkdownBlock, + MarkdownEditor, + ProjectPicker, + usePluginAction, + usePluginData, + usePluginStream, + usePluginToast, + useHostLocation, + useHostNavigation, + type FileTreeNode, + type ManagedRoutinesListItem, + type PluginPageProps, + type PluginRouteSidebarProps, + type PluginSettingsPageProps, + type PluginSidebarProps, +} from "@paperclipai/plugin-sdk/ui"; +import { useCallback, useEffect, useMemo, useRef, useState, type AnchorHTMLAttributes, type CSSProperties, type ReactElement, type ReactNode } from "react"; +import { readIngestOperationIssueId, uploadIssueAttachmentFile } from "./issue-attachments.js"; + +// --------------------------------------------------------------------------- +// Shared design tokens — copied from the UX wireframe shared.css so the plugin +// looks identical inside the host whether or not host theme tokens are +// available at runtime. +// --------------------------------------------------------------------------- + +const tokens = { + border: "var(--border, oklch(0.269 0 0))", + card: "var(--card, oklch(0.205 0 0))", + bg: "var(--background, oklch(0.145 0 0))", + fg: "var(--foreground, oklch(0.985 0 0))", + muted: "var(--muted-foreground, oklch(0.708 0 0))", + accent: "var(--accent, oklch(0.269 0 0))", + primary: "var(--primary, oklch(0.985 0 0))", + primaryFg: "var(--primary-foreground, oklch(0.205 0 0))", + destructive: "var(--destructive, oklch(0.637 0.237 25.331))", + pluginBg: "oklch(0.3 0.06 70)", + pluginFg: "oklch(0.92 0.08 80)", + pluginBorder: "oklch(0.55 0.15 70)", + hiddenOpBg: "oklch(0.27 0.04 280)", + hiddenOpFg: "oklch(0.85 0.08 280)", + hiddenOpBorder: "oklch(0.45 0.1 280)", + callout: { bg: "oklch(0.2 0.04 250)", fg: "oklch(0.85 0.08 250)", border: "oklch(0.4 0.1 250)" }, + statusDone: "oklch(0.65 0.16 145)", + statusRunning: "oklch(0.7 0.13 200)", + statusBlocked: "oklch(0.6 0.21 25)", + statusInProgress: "oklch(0.58 0.18 280)", + statusTodo: "oklch(0.6 0.17 250)", + statusPaused: "oklch(0.72 0.15 70)", +}; + +type Tone = "todo" | "in_progress" | "in_review" | "done" | "blocked" | "running" | "paused" | "failed" | "queued" | "default"; + +const toneStyles: Record = { + default: { background: "var(--secondary, oklch(0.269 0 0))", color: tokens.fg, border: `1px solid ${tokens.border}` }, + todo: { background: "oklch(0.27 0.06 250)", color: "oklch(0.85 0.1 250)" }, + in_progress: { background: "oklch(0.27 0.06 280)", color: "oklch(0.85 0.1 280)" }, + in_review: { background: "oklch(0.27 0.07 305)", color: "oklch(0.85 0.1 305)" }, + done: { background: "oklch(0.27 0.06 145)", color: "oklch(0.85 0.1 145)" }, + blocked: { background: "oklch(0.27 0.08 25)", color: "oklch(0.82 0.13 25)" }, + running: { background: "oklch(0.27 0.06 200)", color: "oklch(0.83 0.11 200)" }, + paused: { background: "oklch(0.27 0.07 70)", color: "oklch(0.85 0.1 70)" }, + failed: { background: "oklch(0.27 0.08 25)", color: "oklch(0.82 0.13 25)" }, + queued: { background: "oklch(0.27 0.06 250)", color: "oklch(0.85 0.1 250)" }, +}; + +const fontStack = `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif`; +const mobileMediaQuery = "(max-width: 767px)"; +const PLUGIN_ID = "paperclipai.plugin-llm-wiki"; +const WIKI_SIDEBAR_NAV_STATE_KEY = "paperclipWikiSidebarTreePath"; +const ROUTE_SIDEBAR_EXPANDED_STORAGE_PREFIX = `${PLUGIN_ID}:route-sidebar-expanded:v2`; +const DEFAULT_ROUTE_SIDEBAR_EXPANDED_PATHS = [ + "wiki", + "wiki/sources", + "wiki/projects", + "wiki/entities", + "wiki/concepts", + "wiki/synthesis", +] as const; + +// --------------------------------------------------------------------------- +// Shared types coming back from the worker. +// --------------------------------------------------------------------------- + +type FolderStatus = { + configured: boolean; + path: string | null; + realPath: string | null; + access: "read" | "readWrite"; + readable: boolean; + writable: boolean; + requiredDirectories: string[]; + requiredFiles: string[]; + missingDirectories: string[]; + missingFiles: string[]; + healthy: boolean; + problems: { code: string; message: string; path?: string }[]; + checkedAt: string; +}; + +type ManagedAgent = { + status: string; + source?: "managed" | "selected"; + agentId?: string | null; + resourceKey?: string | null; + details?: { name?: string; status?: string; adapterType?: string | null; icon?: string | null; urlKey?: string | null } | null; +}; + +type ManagedProject = { + status: string; + source?: "managed" | "selected"; + projectId?: string | null; + resourceKey?: string | null; + details?: { name?: string; status?: string; color?: string | null } | null; +}; + +type ManagedRoutine = { + status: string; + routineId?: string | null; + resourceKey?: string | null; + missingRefs?: Array<{ pluginKey?: string; resourceKind: string; resourceKey: string }>; + routine?: { + id?: string; + title?: string; + status?: string; + assigneeAgentId?: string | null; + projectId?: string | null; + lastTriggeredAt?: string | null; + lastEnqueuedAt?: string | null; + managedByPlugin?: { + pluginDisplayName?: string; + resourceKey?: string; + } | null; + } | null; + details?: { + title?: string; + status?: string; + cronExpression?: string | null; + enabled?: boolean; + nextRunAt?: string | null; + lastRunAt?: string | null; + assigneeAgentId?: string | null; + } | null; +}; + +type OverviewData = { + status: "ok"; + checkedAt: string; + wikiId: string; + folder: FolderStatus; + managedAgent: ManagedAgent; + managedProject: ManagedProject; + operationCount: number; + eventIngestion: EventIngestionSettings; + capabilities: string[]; + prompts: { query: string; lint: string }; +}; + +type EventIngestionSettings = { + enabled: boolean; + sources: { + issues: boolean; + comments: boolean; + documents: boolean; + }; + wikiId: string; + maxCharacters: number; +}; + +type SettingsData = { + folder: FolderStatus; + managedAgent: ManagedAgent; + managedProject: ManagedProject; + managedRoutine?: ManagedRoutine; + managedRoutines?: ManagedRoutine[]; + distillationPolicy?: { + autoApplyAllowed: boolean; + autoApplyRestriction: string | null; + deploymentMode: "local_trusted" | "authenticated" | null; + deploymentExposure: "private" | "public" | null; + }; + eventIngestion: EventIngestionSettings; + agentOptions: Array<{ id: string; name: string; status?: string | null; adapterType?: string | null; icon?: string | null; urlKey?: string | null }>; + projectOptions: Array<{ id: string; name: string; status?: string | null; color?: string | null }>; + capabilities: string[]; +}; + +type WikiPageRow = { + path: string; + title: string | null; + pageType: string | null; + backlinkCount: number; + sourceCount: number; + contentHash: string | null; + updatedAt: string; +}; + +type WikiSourceRow = { + rawPath: string; + title: string | null; + sourceType: string; + url: string | null; + status: string; + createdAt: string; +}; + +type PagesData = { + pages: WikiPageRow[]; + sources: WikiSourceRow[]; +}; + +type PageContentData = { + wikiId: string; + path: string; + contents: string; + title: string | null; + pageType: string | null; + backlinks: string[]; + sourceRefs: string[]; + updatedAt: string | null; + hash: string; +}; + +type WikiOperationRow = { + id: string; + operationType: string; + status: string; + hiddenIssueId: string | null; + hiddenIssueIdentifier: string | null; + hiddenIssueTitle: string | null; + hiddenIssueStatus: string | null; + projectId: string | null; + runIds: unknown[]; + costCents: number; + warnings: unknown[]; + affectedPages: unknown[]; + createdAt: string; + updatedAt: string; +}; + +type OperationsData = { + operations: WikiOperationRow[]; +}; + +type TemplateData = { + path: string; + contents: string; + hash: string | null; + exists: boolean; +}; + +type WikiFrontmatterValue = string | string[]; + +type WikiFrontmatterProperty = { + key: string; + value: WikiFrontmatterValue; +}; + +type ParsedWikiMarkdown = { + body: string; + frontmatter: WikiFrontmatterProperty[]; +}; + +// --------------------------------------------------------------------------- +// Small presentational primitives. +// --------------------------------------------------------------------------- + +function Badge({ children, tone = "default", style }: { children: ReactNode; tone?: Tone; style?: CSSProperties }) { + return ( + {children} + ); +} + +function HiddenOpBadge() { + return ( + 📖 wiki task + ); +} + +function StatusIcon({ status }: { status: string }) { + const map: Record = { + done: { color: tokens.statusDone, filled: true }, + in_progress: { color: tokens.statusInProgress }, + running: { color: tokens.statusRunning, pulse: true }, + queued: { color: tokens.statusTodo }, + todo: { color: tokens.statusTodo }, + blocked: { color: tokens.statusBlocked }, + failed: { color: tokens.statusBlocked }, + paused: { color: tokens.statusPaused }, + }; + const tone = map[status] ?? { color: tokens.muted }; + return ( + + ); +} + +function Card({ children, style }: { children: ReactNode; style?: CSSProperties }) { + return ( +
{children}
+ ); +} + +function CardHeader({ title, right, badges }: { title: ReactNode; right?: ReactNode; badges?: ReactNode }) { + return ( +
+

{title}

+ {badges} + {right ?
{right}
: null} +
+ ); +} + +function CardBody({ children, padding = 16 }: { children: ReactNode; padding?: number | string }) { + return
{children}
; +} + +const unfilledSurfaceStyle: CSSProperties = { + background: "transparent", +}; + +function PropRow({ label, value }: { label: ReactNode; value: ReactNode }) { + return ( +
+ {label} + {value} +
+ ); +} + +function Tiny({ children, style }: { children: ReactNode; style?: CSSProperties }) { + return
{children}
; +} + +function Mono({ children, style }: { children: ReactNode; style?: CSSProperties }) { + return {children}; +} + +type ButtonVariant = "primary" | "default" | "ghost" | "destructive"; +type ButtonSize = "sm" | "md"; + +function Button({ + variant = "default", + size = "md", + disabled, + loading, + onClick, + children, + type = "button", + style, + title, +}: { + variant?: ButtonVariant; + size?: ButtonSize; + disabled?: boolean; + loading?: boolean; + onClick?: () => void; + children: ReactNode; + type?: "button" | "submit"; + style?: CSSProperties; + title?: string; +}) { + const palette: Record = { + primary: { + background: tokens.primary, + color: tokens.primaryFg, + border: `1px solid transparent`, + }, + default: { + background: tokens.card, + color: tokens.fg, + border: `1px solid ${tokens.border}`, + }, + ghost: { + background: "transparent", + color: tokens.fg, + border: `1px solid transparent`, + }, + destructive: { + background: "transparent", + color: "oklch(0.7 0.2 25)", + border: `1px solid oklch(0.5 0.18 25)`, + }, + }; + return ( + + ); +} + +function TextInput(props: React.InputHTMLAttributes) { + return ( + + ); +} + +function TextArea(props: React.TextareaHTMLAttributes) { + return ( +