@codewizard-dt/bootstrap 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# LLM Wiki v2
|
|
2
|
+
|
|
3
|
+
A pattern for building personal knowledge bases using LLMs. Extended with lessons from building [agentmemory](https://github.com/rohitg00/agentmemory) 20K+ Stars ⭐️, a persistent memory engine for AI coding agents.
|
|
4
|
+
|
|
5
|
+
This builds on [Andrej Karpathy's original LLM Wiki idea file](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Everything in the original still applies. This document adds what we learned running the pattern in production: what breaks at scale, what's missing, and what separates a wiki that stays useful from one that rots.
|
|
6
|
+
|
|
7
|
+
## What the original gets right
|
|
8
|
+
|
|
9
|
+
The core insight is correct: **stop re-deriving, start compiling.** RAG retrieves and forgets. A wiki accumulates and compounds. The three-layer architecture (raw sources, wiki, schema) works. The operations (ingest, query, lint) cover the basics. If you haven't read the original, start there.
|
|
10
|
+
|
|
11
|
+
What follows is what we found after building and running this pattern across thousands of sessions.
|
|
12
|
+
|
|
13
|
+
## The missing layer: memory lifecycle
|
|
14
|
+
|
|
15
|
+
The original treats all wiki content as equally valid forever. In practice, knowledge has a lifecycle. A bug you discovered last week matters more than one from six months ago. A pattern you've seen twelve times is more reliable than one you've seen once. A claim from a newer source should weaken an older one automatically.
|
|
16
|
+
|
|
17
|
+
**Confidence scoring.** Every fact in the wiki should carry a confidence score: how many sources support it, how recently it was confirmed, whether anything contradicts it. When the LLM writes "Project X uses Redis for caching," that claim should know it came from two sources, was last confirmed three weeks ago, and sits at confidence 0.85. Confidence decays with time and strengthens with reinforcement. This turns the wiki from a flat collection of equally-weighted claims into a living model where the LLM can say "I'm fairly sure about X but less sure about Y."
|
|
18
|
+
|
|
19
|
+
**Supersession.** When new information contradicts or updates an existing claim, the old claim shouldn't just sit there with a note. The new one should explicitly supersede it. Linked, timestamped, old version preserved but marked stale. Version control for knowledge, not just for files.
|
|
20
|
+
|
|
21
|
+
**Forgetting.** Not everything should live forever. A wiki that never forgets becomes noisy. Implement a retention curve: facts that were important once but haven't been accessed or reinforced in months should gradually fade. Not deleted, but deprioritized. The LLM equivalent of moving something to a bottom drawer. Ebbinghaus's forgetting curve works well here: retention decays exponentially with time, but each reinforcement (access, confirmation from a new source) resets the curve. Architecture decisions decay slowly. Transient bugs decay fast.
|
|
22
|
+
|
|
23
|
+
**Consolidation tiers.** Raw observations aren't the same as established facts. Build a pipeline:
|
|
24
|
+
- **Working memory**: recent observations, not yet processed
|
|
25
|
+
- **Episodic memory**: session summaries, compressed from raw observations
|
|
26
|
+
- **Semantic memory**: cross-session facts, consolidated from episodes
|
|
27
|
+
- **Procedural memory**: workflows and patterns, extracted from repeated semantics
|
|
28
|
+
|
|
29
|
+
Each tier is more compressed, more confident, and longer-lived than the one below it. The LLM promotes information up the tiers as evidence accumulates. This is how you go from "I saw this once" to "this is how things work."
|
|
30
|
+
|
|
31
|
+
## Beyond flat pages: the knowledge graph
|
|
32
|
+
|
|
33
|
+
The original wiki is pages with wikilinks. That works, but you're leaving structure on the table. What you actually want is a typed knowledge graph layered on top of the pages.
|
|
34
|
+
|
|
35
|
+
**Entity extraction.** When the LLM ingests a source, it shouldn't just write prose. It should extract structured entities. People, projects, libraries, concepts, files, decisions. Each entity gets a type, attributes, and relationships to other entities. "React" is a library. "Auth migration" is a project. "Sarah" is a person who owns the auth migration and has opinions about React.
|
|
36
|
+
|
|
37
|
+
**Typed relationships.** Not all connections are equal. "uses," "depends on," "contradicts," "caused," "fixed," "supersedes" carry different semantic weight. A link that says "A relates to B" is less useful than "A caused B, confirmed by 3 sources, confidence 0.9."
|
|
38
|
+
|
|
39
|
+
**Graph traversal for queries.** When someone asks "what's the impact of upgrading Redis?", the LLM shouldn't just keyword-search. It should start at the Redis node, walk outward through "depends on" and "uses" edges, and find everything downstream. This catches connections that keyword search misses.
|
|
40
|
+
|
|
41
|
+
The graph doesn't replace the wiki pages. It augments them. Pages are for reading. The graph is for navigation and discovery.
|
|
42
|
+
|
|
43
|
+
## Search that actually scales
|
|
44
|
+
|
|
45
|
+
The original relies on `index.md`, a single file cataloging every page. This works up to maybe 100-200 pages. Beyond that, the index itself becomes too long for the LLM to read in one pass, and you need real search.
|
|
46
|
+
|
|
47
|
+
**Hybrid search.** The best approach combines three streams:
|
|
48
|
+
- **BM25** (keyword matching with stemming and synonym expansion)
|
|
49
|
+
- **Vector search** (semantic similarity via embeddings)
|
|
50
|
+
- **Graph traversal** (entity-aware relationship walking)
|
|
51
|
+
|
|
52
|
+
Fuse the results with reciprocal rank fusion. Each stream catches things the others miss. BM25 finds exact terms. Vectors find semantic similarity. The graph finds structural connections. Together they beat any single approach.
|
|
53
|
+
|
|
54
|
+
Keep `index.md` as a human-readable catalog, but don't rely on it as the LLM's primary search mechanism past ~100 pages.
|
|
55
|
+
|
|
56
|
+
## Automation: from manual to event-driven
|
|
57
|
+
|
|
58
|
+
The biggest practical gap in the original is that everything is manual. You drop a source and tell the LLM to process it. You remember to run lint periodically. You decide when to file an answer back.
|
|
59
|
+
|
|
60
|
+
In practice, you want hooks. Events that fire automatically:
|
|
61
|
+
|
|
62
|
+
- **On new source**: auto-ingest, extract entities, update graph, update index
|
|
63
|
+
- **On session start**: load relevant context from the wiki based on recent activity
|
|
64
|
+
- **On session end**: compress the session into observations, file insights
|
|
65
|
+
- **On query**: check if the answer is worth filing back (quality score > threshold)
|
|
66
|
+
- **On memory write**: check for contradictions with existing knowledge, trigger supersession
|
|
67
|
+
- **On schedule**: periodic lint, consolidation, retention decay
|
|
68
|
+
|
|
69
|
+
The human should still be in the loop for curation and direction. But the bookkeeping, the part that makes people abandon wikis, should be fully automated.
|
|
70
|
+
|
|
71
|
+
## Quality and self-correction
|
|
72
|
+
|
|
73
|
+
Not all LLM-generated content is good. Without quality controls, the wiki accumulates noise.
|
|
74
|
+
|
|
75
|
+
**Score everything.** Every piece of content the LLM writes should get a quality score. Is it well-structured? Does it cite sources? Is it consistent with the rest of the wiki? You can have the LLM self-evaluate, or use a second pass with a different prompt. Content below a threshold gets flagged for review or rewritten.
|
|
76
|
+
|
|
77
|
+
**Self-healing.** The lint operation from the original should be more than a suggestion. It should automatically fix what it can. Orphan pages get linked or flagged. Stale claims get marked. Broken cross-references get repaired. The wiki should tend toward health on its own, not only when you remember to ask.
|
|
78
|
+
|
|
79
|
+
**Contradiction resolution.** The original mentions flagging contradictions. That's step one. Step two is resolving them. The LLM should propose which claim is more likely correct based on source recency, source authority, and the number of supporting observations. The human can override, but the default behavior should usually be right.
|
|
80
|
+
|
|
81
|
+
## Multi-agent and collaboration
|
|
82
|
+
|
|
83
|
+
The original is single-user, single-agent. Many real use cases involve multiple agents or multiple people contributing to the same knowledge base.
|
|
84
|
+
|
|
85
|
+
**Mesh sync.** If multiple agents are working in parallel (different coding sessions, different research threads), their observations need to merge into a shared wiki. Last-write-wins works for most cases. For conflicts, timestamp-based resolution with manual override.
|
|
86
|
+
|
|
87
|
+
**Shared vs. private.** Some knowledge is personal (my preferences, my workflow). Some is shared (project architecture, team decisions). The wiki needs scoping. Private observations that roll up into shared knowledge when promoted.
|
|
88
|
+
|
|
89
|
+
**Work coordination.** When multiple agents work on the same knowledge base, they need lightweight coordination. Who's working on what. What's blocked. What's done. Not a full task management system, just enough to prevent duplicate work and track progress.
|
|
90
|
+
|
|
91
|
+
## Privacy and governance
|
|
92
|
+
|
|
93
|
+
The original doesn't mention this, but it matters. Sources often contain sensitive information: API keys, credentials, private conversations, PII.
|
|
94
|
+
|
|
95
|
+
**Filter on ingest.** Before anything hits the wiki, strip sensitive data. API keys, tokens, passwords, anything marked private. This should be automatic, not something you remember to do.
|
|
96
|
+
|
|
97
|
+
**Audit trail.** Every operation on the wiki (ingest, edit, delete, query) should be logged with a timestamp, what changed, and why. This is your accountability layer. When something looks wrong in the wiki, the audit trail tells you how it got there.
|
|
98
|
+
|
|
99
|
+
**Bulk operations with governance.** As the wiki grows, you'll want to bulk-delete stale content, export subsets, or merge duplicate entities. These operations should be audited and reversible.
|
|
100
|
+
|
|
101
|
+
## Crystallization: compounding from exploration
|
|
102
|
+
|
|
103
|
+
The original mentions that "good answers can be filed back into the wiki as new pages." This can be taken further.
|
|
104
|
+
|
|
105
|
+
**Crystallization** is the process of taking a completed chain of work (a research thread, a debugging session, an analysis) and automatically distilling it into a structured digest. What was the question? What did we find? What files/entities were involved? What lessons emerged? This digest becomes a first-class wiki page, and the lessons get extracted as standalone facts that strengthen the knowledge base.
|
|
106
|
+
|
|
107
|
+
Your explorations are a source, just like an article or a paper. The wiki should treat them that way. Ingest the results, update the graph, strengthen or challenge existing claims.
|
|
108
|
+
|
|
109
|
+
## Output formats beyond markdown
|
|
110
|
+
|
|
111
|
+
The original mentions Marp for slide decks and matplotlib for charts. The wiki's output shouldn't be limited to markdown pages. Depending on the query, the right output might be:
|
|
112
|
+
|
|
113
|
+
- A comparison table
|
|
114
|
+
- A timeline visualization
|
|
115
|
+
- A dependency graph
|
|
116
|
+
- A slide deck for presenting findings
|
|
117
|
+
- A structured data export (JSON, CSV) for further analysis
|
|
118
|
+
- A brief for someone else on your team
|
|
119
|
+
|
|
120
|
+
The wiki is the knowledge store. The output format depends on the audience and the question.
|
|
121
|
+
|
|
122
|
+
## The schema is the real product
|
|
123
|
+
|
|
124
|
+
The original implies this but it's worth being direct: **the schema document (CLAUDE.md, AGENTS.md) is the most important file in the system.** It's what turns a generic LLM into a disciplined knowledge worker. It encodes:
|
|
125
|
+
|
|
126
|
+
- What types of entities and relationships exist in your domain
|
|
127
|
+
- How to ingest different kinds of sources
|
|
128
|
+
- When to create a new page vs. update an existing one
|
|
129
|
+
- What quality standards to apply
|
|
130
|
+
- How to handle contradictions
|
|
131
|
+
- What the consolidation schedule looks like
|
|
132
|
+
- What's private vs. shared
|
|
133
|
+
|
|
134
|
+
You and the LLM co-evolve this document over time. The first version will be rough. After a few dozen sources and a few lint passes, you'll have a schema that reflects how your domain actually works. That schema is transferable. Share it with someone else working on a similar domain and they get a running start.
|
|
135
|
+
|
|
136
|
+
## Implementation spectrum
|
|
137
|
+
|
|
138
|
+
All of this is modular. You don't need everything on day one.
|
|
139
|
+
|
|
140
|
+
**Minimal viable wiki**: raw sources + wiki pages + index.md + a schema that describes ingest/query/lint workflows. This is roughly what the original describes. It works. Start here.
|
|
141
|
+
|
|
142
|
+
**Add lifecycle**: confidence scoring, supersession, basic retention decay. This prevents the wiki from becoming a junk drawer.
|
|
143
|
+
|
|
144
|
+
**Add structure**: entity extraction, typed relationships, knowledge graph. This makes queries better and surfaces connections you'd miss with flat pages.
|
|
145
|
+
|
|
146
|
+
**Add automation**: hooks for auto-ingest, auto-lint, context injection. This is where the maintenance burden drops to near zero.
|
|
147
|
+
|
|
148
|
+
**Add scale**: hybrid search, consolidation tiers, quality scoring. This is what you need when the wiki grows past a few hundred pages.
|
|
149
|
+
|
|
150
|
+
**Add collaboration**: mesh sync, shared/private scoping, work coordination. This is for teams or multi-agent setups.
|
|
151
|
+
|
|
152
|
+
Pick your entry point based on your needs. The pattern works at every level.
|
|
153
|
+
|
|
154
|
+
## Why this matters
|
|
155
|
+
|
|
156
|
+
Karpathy's original insight stands: the bottleneck is bookkeeping, and LLMs eliminate that bottleneck. What we've added is the machinery that keeps the wiki healthy as it scales. Lifecycle management so knowledge doesn't rot. Structure so connections aren't lost. Automation so humans stay focused on thinking rather than filing. Quality controls so the wiki earns trust over time.
|
|
157
|
+
|
|
158
|
+
The Memex is finally buildable. Not because we have better documents or better search, but because we have librarians that actually do the work.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
*This document extends [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) with patterns proven in [agentmemory](https://github.com/rohitg00/agentmemory), a persistent memory engine for AI agents built on [iii-engine](https://github.com/iii-hq/iii). The original idea file is the foundation; this adds what we learned building the engine.*
|
package/raw/llm-wiki.md
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# LLM Wiki
|
|
2
|
+
|
|
3
|
+
A pattern for building personal knowledge bases using LLMs.
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
## The core idea
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
This can apply to a lot of different contexts. A few examples:
|
|
18
|
+
|
|
19
|
+
- **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.
|
|
20
|
+
- **Research**: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
|
|
21
|
+
- **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.
|
|
22
|
+
- **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.
|
|
23
|
+
- **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.
|
|
24
|
+
|
|
25
|
+
## Architecture
|
|
26
|
+
|
|
27
|
+
There are three layers:
|
|
28
|
+
|
|
29
|
+
**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.
|
|
30
|
+
|
|
31
|
+
**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.
|
|
32
|
+
|
|
33
|
+
**The schema** — a document (e.g. CLAUDE.md for Claude Code or AGENTS.md for Codex) 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.
|
|
34
|
+
|
|
35
|
+
## Operations
|
|
36
|
+
|
|
37
|
+
**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.
|
|
38
|
+
|
|
39
|
+
**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.
|
|
40
|
+
|
|
41
|
+
**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.
|
|
42
|
+
|
|
43
|
+
## Indexing and logging
|
|
44
|
+
|
|
45
|
+
Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:
|
|
46
|
+
|
|
47
|
+
**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.
|
|
48
|
+
|
|
49
|
+
**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.
|
|
50
|
+
|
|
51
|
+
## Optional: CLI tools
|
|
52
|
+
|
|
53
|
+
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.
|
|
54
|
+
|
|
55
|
+
## Tips and tricks
|
|
56
|
+
|
|
57
|
+
- **Obsidian Web Clipper** is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
|
|
58
|
+
- **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.
|
|
59
|
+
- **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.
|
|
60
|
+
- **Marp** is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
|
|
61
|
+
- **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.
|
|
62
|
+
- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.
|
|
63
|
+
|
|
64
|
+
## Why this works
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
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.
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
## Note
|
|
74
|
+
|
|
75
|
+
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.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: plan to implement a dark mode theme
|
|
3
|
+
slug: dark-mode-theme
|
|
4
|
+
researched: 2026-07-06
|
|
5
|
+
sources: [./sources.md]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Research: Dark Mode Theme for the Wiki Dashboard
|
|
9
|
+
|
|
10
|
+
> `TASK-002-wiki-dashboard-client.md` requires light/dark theming for `dashboard.html` via `@media (prefers-color-scheme: dark)` "at minimum," but no concrete palette, CSS-variable structure, or toggle mechanism exists anywhere in this repo. Recommendation: implement a full explicit-override toggle (`localStorage` > OS `prefers-color-scheme` > default), backed by a dark palette derived from the existing `raw/house-style` light tokens, following the CSS-custom-property + `data-theme` attribute pattern that is the 2025 industry-converged approach for self-contained static pages.
|
|
11
|
+
|
|
12
|
+
## Research Questions
|
|
13
|
+
|
|
14
|
+
- Does this repo have any existing dark-mode/theme convention `dashboard.html` should follow?
|
|
15
|
+
- What does the wiki-dashboard roadmap (ROADMAP-002) and its sibling tasks (TASK-001/003/004/005) say about theming?
|
|
16
|
+
- What is current (2025) best practice for implementing a light/dark toggle in a dependency-free vanilla HTML/CSS/JS file?
|
|
17
|
+
- What palette should the dark theme use, given `raw/house-style` is light-mode only?
|
|
18
|
+
- How does theming interact with `dashboard.html`'s live-polling render loop?
|
|
19
|
+
|
|
20
|
+
## Current State (Codebase)
|
|
21
|
+
|
|
22
|
+
- `wiki/work/tasks/TASK-002-wiki-dashboard-client.md` (lines 27, 36) is the only place in the repo that mentions theming: "Theme: support light/dark via `prefers-color-scheme` media query at minimum" — stated as a floor, not a full spec.
|
|
23
|
+
- `wiki/work/tasks/TASK-001-wiki-dashboard-server.md`, `TASK-003-wiki-dashboard-cli-wiring.md`, `TASK-004-wiki-dashboard-sync-scaffold.md`, `TASK-005-wiki-dashboard-docs.md`, and the parent `ROADMAP-002` file contain zero mentions of "dark," "theme," "light mode," `prefers-color-scheme`, CSS variables, or a toggle. They cover the static server, CLI wiring, scaffold distribution, and docs respectively — none touch `dashboard.html`'s markup/CSS/JS content, which is entirely TASK-002's scope.
|
|
24
|
+
- `raw/house-style/tokens/tokens.json` (the repo's design-token source of truth) defines only light-mode colors: `canvas #f6f7f9`, `surface #f1f2f4`, `card #ffffff`, `ink #0b0b0d`, `ink-2 #33353b`, `muted #6b6e76`, `muted-2 #9a9da5`, `line #e7e8ea`, `accent #4f5a78`, plus status accents (`red #e5484d`, `green #30a46c`, `blue #3b6ef6`, `amber #e0901a`, `violet #8b5cf6`). No dark variants exist.
|
|
25
|
+
- `raw/house-style/preview/src/index.css` confirms there is no dark-mode handling anywhere in the house-style preview — no `prefers-color-scheme`, no `data-theme`.
|
|
26
|
+
- `dashboard.html` itself does not exist yet; TASK-002 (status: `todo`) is what will create `lib/scripts/templates/wiki/dashboard.html`, and it plans a 5-second polling loop (`renderFamily()` / `setInterval`) that re-renders all six family panels — any theme toggle must live outside that regenerated DOM subtree.
|
|
27
|
+
- The nearest usable structural reference on this machine (outside this repo) is `~/.claude/plugins/marketplaces/claude-plugins-official/plugins/project-artifact/skills/project-artifact/template.html`, which implements `:root` custom properties + `@media (prefers-color-scheme: dark)` overrides (no manual toggle) — the right shape to extend, but missing the explicit-override layer.
|
|
28
|
+
|
|
29
|
+
## Key Findings
|
|
30
|
+
|
|
31
|
+
- No dark-mode precedent or convention exists anywhere in `bootstrap-claude` to reuse — this had to be designed fresh. [S1][S2][S3]
|
|
32
|
+
- `dashboard.html` is a plain static file served by TASK-001's Node server and opened directly in a browser; it is **not** a Claude Artifact, so the Artifact tool's "host stamps `data-theme`" behavior does not apply — the toggle logic must be fully self-contained in the file itself. *(inference from Artifact tool documentation — no primary source file)*
|
|
33
|
+
- 2025 best-practice consensus across multiple independent sources is a **tri-state cascade**: explicit `localStorage` choice > OS `prefers-color-scheme` > default, resolved via an inline script that runs before first paint to avoid a flash of the wrong theme (FOUC/FOWT). [S4][S5][S6]
|
|
34
|
+
- CSS structure: define color tokens as custom properties in `:root` (light defaults) and override them in `@media (prefers-color-scheme: dark)` as a passive fallback; then define `:root[data-theme="light"]` / `:root[data-theme="dark"]` blocks after the media query so an explicit attribute always wins at equal specificity. [S6][S7]
|
|
35
|
+
- Accessibility/UX details repeatedly emphasized: avoid pure-black backgrounds (use ~`#17181c`–`#1c1d21`); add `<meta name="color-scheme" content="light dark">` so native scrollbars/form controls theme correctly; give the toggle a real `aria-label`; respect `prefers-reduced-motion` for any color-transition animation. [S5][S8]
|
|
36
|
+
- `localStorage` reads/writes should be wrapped in `try/catch` since they can throw in locked-down or private-browsing contexts — theming should degrade gracefully to media-query-only rather than break the page. *(inference — no single primary source states this explicitly, but it follows from standard defensive JS practice)*
|
|
37
|
+
|
|
38
|
+
## Constraints
|
|
39
|
+
|
|
40
|
+
- No build step and no external dependencies — `dashboard.html` must remain a single self-contained file (per TASK-002's stated constraint), so no CSS/theming library or framework can be introduced.
|
|
41
|
+
- Must not regress the existing 5-second polling/re-render loop; the toggle button and its listener must survive every re-render cycle.
|
|
42
|
+
- Must derive from `raw/house-style` tokens where possible for light-mode consistency with the rest of the ecosystem, even though house-style has no dark equivalents to copy directly.
|
|
43
|
+
|
|
44
|
+
## Recommendation
|
|
45
|
+
|
|
46
|
+
**Recommended approach: full explicit-override toggle**, not a bare media query.
|
|
47
|
+
|
|
48
|
+
**Palette** (dark values derived from the existing light `tokens.json`, keeping hue relationships, lightening saturated accents ~10–15% for contrast on dark backgrounds, avoiding pure black):
|
|
49
|
+
|
|
50
|
+
| Token | Light (existing, from `tokens.json`) | Dark (new) |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| `--bg` | `#f6f7f9` | `#16171a` |
|
|
53
|
+
| `--surface` | `#f1f2f4` | `#1c1d21` |
|
|
54
|
+
| `--card` | `#ffffff` | `#202127` |
|
|
55
|
+
| `--text` | `#0b0b0d` | `#e8e9ec` |
|
|
56
|
+
| `--text-2` | `#33353b` | `#c3c5cb` |
|
|
57
|
+
| `--muted` | `#6b6e76` | `#9a9da5` |
|
|
58
|
+
| `--border` | `#e7e8ea` | `#303238` |
|
|
59
|
+
| `--accent` | `#4f5a78` | `#8891ab` |
|
|
60
|
+
| `--red` | `#e5484d` | `#ff6b70` |
|
|
61
|
+
| `--green` | `#30a46c` | `#3ddc91` |
|
|
62
|
+
| `--blue` | `#3b6ef6` | `#6e93ff` |
|
|
63
|
+
| `--amber` | `#e0901a` | `#f0a83a` |
|
|
64
|
+
| `--violet` | `#8b5cf6` | `#a78bfa` |
|
|
65
|
+
|
|
66
|
+
**Implementation outline** (for TASK-002 steps 1 and 3):
|
|
67
|
+
|
|
68
|
+
1. `:root { --bg: #f6f7f9; ... }` (light defaults) + `@media (prefers-color-scheme: dark) { :root { --bg: #16171a; ... } }` as the passive fallback.
|
|
69
|
+
2. `:root[data-theme="light"] { ... }` / `:root[data-theme="dark"] { ... }` blocks placed *after* the media query in source order, so an explicit attribute wins over the media query.
|
|
70
|
+
3. An inline `<script>` near the top of `<body>`, run synchronously before the rest of the page paints: read `localStorage.getItem('dashboard-theme')`; if present, set `document.documentElement.setAttribute('data-theme', saved)` immediately. If absent, leave the attribute unset (media query governs) and attach a `matchMedia('(prefers-color-scheme: dark)')` change listener so a live OS flip is reflected while no explicit choice exists.
|
|
71
|
+
4. A toggle `<button aria-label="Switch color theme">` in the static header: on click, compute the currently-resolved theme, flip it, `setAttribute('data-theme', next)` + `localStorage.setItem('dashboard-theme', next)`.
|
|
72
|
+
5. `<meta name="color-scheme" content="light dark">` in `<head>`.
|
|
73
|
+
6. Wrap any theme-swap transition in `@media (prefers-reduced-motion: no-preference)`.
|
|
74
|
+
|
|
75
|
+
**Risks and mitigations:**
|
|
76
|
+
- Polling loop could wipe the toggle button if rendering is scoped too broadly → keep `renderFamily()`/panel rendering confined to a container below the static header.
|
|
77
|
+
- `localStorage` can throw in private/locked-down browsing → wrap in `try/catch`, degrade to media-query-only.
|
|
78
|
+
- Dark palette values above are a starting point, not contrast-checked — verify WCAG AA (4.5:1 body text) once real markup exists.
|
|
79
|
+
|
|
80
|
+
**Alternative if constraints change**: if a future requirement demands matching an exact design tool's dark palette (e.g. a rebuilt house-style with real dark tokens), swap only the palette table above — the CSS-variable/`data-theme` structure does not need to change.
|
|
81
|
+
|
|
82
|
+
## Next Steps
|
|
83
|
+
|
|
84
|
+
- Implementation: this is guidance for existing `TASK-002` (`wiki/work/tasks/TASK-002-wiki-dashboard-client.md`) — no new task needed. Consider amending TASK-002 steps 1 & 3 with the palette table and toggle structure above so the implementer doesn't re-derive it.
|
|
85
|
+
- To ingest into the knowledge base: `/wiki-ingest raw/research/dark-mode-theme/index.md`
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: plan to implement a dark mode theme
|
|
3
|
+
slug: dark-mode-theme
|
|
4
|
+
researched: 2026-07-06
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Primary Sources — Dark Mode Theme for the Wiki Dashboard
|
|
8
|
+
|
|
9
|
+
| ID | Type | Locator | Accessed | What it contributed |
|
|
10
|
+
|----|------|---------|----------|---------------------|
|
|
11
|
+
| S1 | codebase | `wiki/work/tasks/TASK-002-wiki-dashboard-client.md` (lines 27, 36) | 2026-07-06 | The only theming requirement in the repo: "support light/dark via `prefers-color-scheme` media query at minimum" |
|
|
12
|
+
| S2 | codebase | `wiki/work/tasks/TASK-001-wiki-dashboard-server.md`, `TASK-003-wiki-dashboard-cli-wiring.md`, `TASK-004-wiki-dashboard-sync-scaffold.md`, `TASK-005-wiki-dashboard-docs.md`, `wiki/work/roadmaps/` (ROADMAP-002) | 2026-07-06 | Confirmed zero mentions of dark mode/theming anywhere else in the roadmap or sibling tasks; established that TASK-002 is the sole owner of `dashboard.html` content |
|
|
13
|
+
| S3 | codebase | `raw/house-style/tokens/tokens.json` | 2026-07-06 | The repo's only color-token source of truth; confirmed light-mode-only (no dark values, no `data-theme` reference) — basis for deriving the dark palette |
|
|
14
|
+
| S4 | web | https://whitep4nth3r.com/blog/best-light-dark-mode-theme-toggle-javascript/ | 2026-07-06 | Tri-state "preference cascade" pattern: `localStorage` choice, falling back to `matchMedia('(prefers-color-scheme: dark)')`, falling back to a default |
|
|
15
|
+
| S5 | web | https://blog.openreplay.com/build-dark-mode-toggle-css-js/ | 2026-07-06 | `<meta name="color-scheme" content="light dark">` for native control theming; `data-theme` on `<html>`; script-before-paint to prevent flash; accessible toggle button with `aria-label` |
|
|
16
|
+
| S6 | web | https://www.magicpatterns.com/blog/implementing-dark-mode | 2026-07-06 | `:root[data-theme="dark"]` custom-property override pattern so consuming component CSS never needs to change per theme |
|
|
17
|
+
| S7 | web | https://medium.com/@cerutti.alexander/a-mostly-complete-guide-to-theme-switching-in-css-and-js-c4992d5fd357 | 2026-07-06 | Confirms `@media (prefers-color-scheme)` + `[data-theme]` attribute can coexist, covering all four system/setting combinations; explains why the attribute override must come after the media query in source order |
|
|
18
|
+
| S8 | web | https://www.srfdeveloper.com/2025/08/css-javascript-dark-mode-toggle.html | 2026-07-06 | "A user's explicit choice (clicking our toggle) should always win" over OS preference; avoid pure-black dark backgrounds |
|
|
19
|
+
| S9 | codebase | `~/.claude/plugins/marketplaces/claude-plugins-official/plugins/project-artifact/skills/project-artifact/template.html` | 2026-07-06 | Reference implementation of `:root` custom properties + `@media (prefers-color-scheme: dark)` override (no manual toggle) — structural starting point |
|
|
20
|
+
|
|
21
|
+
## Excerpts
|
|
22
|
+
|
|
23
|
+
### S1 — TASK-002-wiki-dashboard-client.md
|
|
24
|
+
`wiki/work/tasks/TASK-002-wiki-dashboard-client.md`
|
|
25
|
+
> Theme: support light/dark via `prefers-color-scheme` media query at minimum (this repo's Artifact convention favors theme-awareness; apply the same care here since it's a long-running local tool a developer will have open).
|
|
26
|
+
|
|
27
|
+
### S3 — tokens.json
|
|
28
|
+
`raw/house-style/tokens/tokens.json`
|
|
29
|
+
> "color": { "canvas": "#f6f7f9", "surface": "#f1f2f4", "paper": "#ffffff", "card": "#ffffff", "ink": "#0b0b0d", "ink-2": "#33353b", "muted": "#6b6e76", "muted-2": "#9a9da5", "line": "#e7e8ea", "line-2": "#f0f1f3", "accent": "#4f5a78", "accent-red": "#e5484d", "accent-green": "#30a46c", "accent-blue": "#3b6ef6", "accent-amber": "#e0901a", "accent-violet": "#8b5cf6", "accent-rose": "#f43f5e" }
|
|
30
|
+
|
|
31
|
+
### S4 — whitep4nth3r.com
|
|
32
|
+
https://whitep4nth3r.com/blog/best-light-dark-mode-theme-toggle-javascript/
|
|
33
|
+
> If there's no stored theme preference in localStorage, we'll detect the user's system settings using the window.matchMedia() method by passing in a media query string... const systemSettingDark = window.matchMedia("(prefers-color-scheme: dark)");
|
|
34
|
+
|
|
35
|
+
### S5 — openreplay.com
|
|
36
|
+
https://blog.openreplay.com/build-dark-mode-toggle-css-js/
|
|
37
|
+
> Place a script immediately after the body tag that checks localStorage and applies the saved theme before the page paints to prevent this flash... Should I use pure black for dark mode backgrounds? No, pure black can cause eye strain... Use dark grays like #1a1a1a or #121212 instead.
|
|
38
|
+
|
|
39
|
+
### S6 — magicpatterns.com
|
|
40
|
+
https://www.magicpatterns.com/blog/implementing-dark-mode
|
|
41
|
+
> :root { --primary-color: #9f7aea; --border-color: #000000; } :root[data-theme="dark"] { --primary-color: #6B46C1; --border-color: #ffffff; } ... The beauty with this implementation is that the consuming code doesn't need to change at all.
|
|
42
|
+
|
|
43
|
+
### S7 — Alexander Cerutti, Medium
|
|
44
|
+
https://medium.com/@cerutti.alexander/a-mostly-complete-guide-to-theme-switching-in-css-and-js-c4992d5fd357
|
|
45
|
+
> Now, using @media (prefers-color-scheme: dark | light) in CSS code is completely optional, as we can use exclusively the newly created [data-theme] attribute. If you still want to use it, you should be prepared to handle all the four cases: system:light-setting:light, system:light-setting:dark, system:dark-setting:dark, system:dark-setting-light.
|
|
46
|
+
|
|
47
|
+
### S8 — srfdeveloper.com
|
|
48
|
+
https://www.srfdeveloper.com/2025/08/css-javascript-dark-mode-toggle.html
|
|
49
|
+
> Our logic should be: a user's *explicit choice* (clicking our toggle) should always win. But if they've never made a choice on our site, we should respect their OS setting as the default.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: "Recent hook changes to Serena MCP health-checking appear to be causing Serena's MCP server to disconnect mid-session, almost every session — evidenced by: 'Serena's MCP server disconnected mid-session, so exploration fell back to Read/Bash — didn't block anything since the README/wiki already had the architecture fully synthesized.'"
|
|
3
|
+
slug: serena-mcp-disconnect
|
|
4
|
+
researched: 2026-07-07
|
|
5
|
+
sources: [./sources.md]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Research: Serena MCP server disconnects mid-session after the health-tracking hook change
|
|
9
|
+
|
|
10
|
+
> **The health-tracking hook doesn't just detect a dead Serena server — under a common, everyday condition it actively kills a live, healthy one.** `classifySerenaFailure()` defaults *any* unrecognized error string to `'transport'` (assess-and-possibly-kill) instead of `'tool'` (log-and-continue). A completely benign, expected error — Serena declining to parse a file whose language isn't enabled in `.serena/project.yml` — doesn't match the narrow tool-level regex, falls through to the transport branch, and `attemptSerenaRestart()` then `pkill`s the process on the false premise that "alive but returned an error" means "hung." Since Claude Code has no documented way to reconnect a stdio MCP server mid-session, the kill is effectively permanent for the rest of that session. This was caught live, in real time, during this research: three parallel `get_symbols_overview` calls on this repo's own `.js` hook files (JS/TS isn't in this project's enabled Serena languages) triggered exactly this sequence, and `ps aux` confirms the `bootstrap-claude` Serena process is gone while two other concurrently open projects' Serena processes are untouched. A related concurrency bug (unsynchronized read-modify-write on the shared per-project state file) then left the enforcement flag in an inconsistent state — `should_enforce: true` while the process is confirmed dead — which is the exact deadlock shape that would explain "almost every session."
|
|
11
|
+
|
|
12
|
+
## Research Questions
|
|
13
|
+
- What changed in the recent Serena health-tracking hook work, and does it plausibly cause server disconnects?
|
|
14
|
+
- Can the disconnect be reproduced/observed directly, and what is the precise trigger?
|
|
15
|
+
- Is there a design flaw in how "hung" vs. "dead" vs. "erroring-but-alive" is distinguished?
|
|
16
|
+
- Is there a secondary bug (e.g. concurrency) that compounds the problem?
|
|
17
|
+
- What's the minimal, safe fix?
|
|
18
|
+
|
|
19
|
+
## Current State (Codebase)
|
|
20
|
+
|
|
21
|
+
The hook chain lives in `lib/hooks/` (mirrored to `~/.claude/hooks/` by `install-global.sh`):
|
|
22
|
+
|
|
23
|
+
- **`lib/hooks/lib/serena.js`** — shared helper. Added in commit `5752eed` ("Add Serena health tracking with fail-open enforcement..."): a per-project JSON state file (`~/.claude/state/lsp-ready-<md5(cwd).slice(0,12)>`) now carries a `health` sub-object (`should_enforce`, `healthy`, `error_count`, `last_error`, `last_check`, `notified`), plus new functions `classifySerenaFailure()`, `isSerenaProcessAlive()`, and `attemptSerenaRestart()` [S1].
|
|
24
|
+
- **`lib/hooks/serena-usage-tracker.js`** — `PostToolUse` + `PostToolUseFailure` hook, registered under matcher `mcp__serena__.*|mcp__plugin_[^_]+_serena__.*` in `~/.claude/settings.json` [S4]. On any Serena tool call: success restores health; failure is classified and, if `'transport'`, drives `handleFailure()` → process-liveness probe → possible restart → fail-open [S2].
|
|
25
|
+
- **`lib/hooks/serena-first-read-guard.js`** — Gate 1 blocks the very first `Read` on a code file until `mcp__serena__get_symbols_overview` (or another nav tool) has been called at least once (`warmup_done`); Gates 4/5 require increasing `nav_count` before more Reads unlock. All gates are skipped only if `shouldEnforceSerena(flag)` is false [S3].
|
|
26
|
+
- **`.serena/project.yml`** for this repo enables only `languages: [bash, markdown, yaml]` — **not** `typescript` (the config file's own comment says "For JavaScript, use typescript") [S5]. But this repo's own tooling — `lib/hooks/*.js`, `lib/scripts/*.js`, `bin/cli.js` — is JavaScript.
|
|
27
|
+
- The user-level global rule `~/.claude/rules/lsp-first.md` instructs **all agents** to call `find_symbol`/`get_symbols_overview` first for any code navigation, with no carve-out for files whose language isn't enabled in the current project's Serena config.
|
|
28
|
+
|
|
29
|
+
## Key Findings
|
|
30
|
+
|
|
31
|
+
1. **The exact failure was reproduced live, in this session, on this repo.** Three parallel `mcp__serena__get_symbols_overview` calls against `lib/hooks/lib/serena.js`, `lib/hooks/serena-session-reset.js`, and `lib/hooks/serena-usage-tracker.js` each failed with `ValueError: Cannot extract symbols from file <path>. Active languages: ['bash', 'markdown', 'yaml']` — because JS/TS isn't an enabled language for this project [S6]. Immediately after, the system surfaced: *"The following MCP servers have disconnected: serena."* [S7]
|
|
32
|
+
|
|
33
|
+
2. **`classifySerenaFailure()` misclassifies this benign error as a transport failure.** Its tool-level regex — `not found|no results|no matching|no symbol|could not find|error searching|error finding|does not exist|no such (?:file|symbol|path|directory)|error at` — does not match "Cannot extract symbols... Active languages: [...]". The function's own comment says "Unknown ⇒ transport (assess health rather than silently ignore)" [S1, lines 449–472] — meaning *any* Serena error message the author didn't anticipate defaults to the destructive path.
|
|
34
|
+
|
|
35
|
+
3. **`attemptSerenaRestart()` kills a process that just proved it was alive.** The function's premise: if `isSerenaProcessAlive()` is true after a failure, the process must be "hung," so `pkill -f 'serena start-mcp-server.*<projectDir>'` is issued, followed by a 1s sleep and a re-probe [S1, lines 492–509]. This is a logical inversion: a `PostToolUseFailure`/error `tool_response` can only fire if the MCP round-trip *completed* — the server necessarily responded. A genuinely hung or dead process would never produce a parseable error payload for this hook to classify in the first place. The hook's own code comment even acknowledges the fix is unrecoverable: *"There is no documented way to reconnect a stdio MCP server mid-session, so a successful 'restart' only happens if the host respawns the process."* [S1, lines 495–497]
|
|
36
|
+
|
|
37
|
+
4. **Empirically confirmed via `ps aux`.** No `serena start-mcp-server ... bootstrap-claude` process exists post-incident, while `serena start-mcp-server ... portfolio_v2` and `... gauntlet/demand-letter` (two other projects open in sibling sessions at the same time) are both alive and untouched [S8]. This rules out a host-level/global Serena outage — the kill was scoped to exactly the project whose hook fired.
|
|
38
|
+
|
|
39
|
+
5. **The per-project state file confirms the exact trigger and reveals a second bug.** `~/.claude/state/lsp-ready-6d7a97f1dd99` (the `bootstrap-claude` state file) shows `last_error` verbatim matching the reproduction above, `healthy: false`, but **`should_enforce: true`** [S9] — an inconsistent combination the code's own contract says should not occur (`should_enforce` is meant to flip to `false` exactly when `attemptSerenaRestart` finds no live process remaining, per `handleFailure()`'s final branch [S1, lines 170–189]). Root cause: `serena-usage-tracker.js` does an unsynchronized `readStateFile → mutate → writeStateFile` with no locking [S2, lines 122–189; `writeStateFile` at S1 lines 399–404]. The three parallel `get_symbols_overview` failures in this session raced: `error_count: 2` (not 3 — one write was clobbered), and the write that correctly set `should_enforce: false` was overwritten by a losing, stale write from another concurrent invocation.
|
|
40
|
+
|
|
41
|
+
6. **This inconsistent state reproduced the deadlock live, moments later.** Immediately after, a plain `ls`/`find` via Bash on `raw/research/` was blocked by `serena-bash-grep-block.js`'s SERENA-FIRST guard — even though Serena is confirmed dead — because the guard reads `should_enforce: true` from the (corrupted) state file and has no independent way to know the process is gone. Work only proceeded via a `python3 -c` one-liner that doesn't match the guard's command patterns.
|
|
42
|
+
|
|
43
|
+
7. **In a fresh session, this is the "almost every time" mechanism.** `serena-session-reset.js` wipes `nav_count`/`warmup_done` to zero at `SessionStart` [S10]. `serena-first-read-guard.js` Gate 1 then blocks the *first* code `Read` until a Serena nav call succeeds [S3, lines 55–67]. Per the global LSP-first rule, the agent's first move on a code file is `get_symbols_overview`. If that first file is one of this project's own `.js` hook/script files (a near-certainty when exploring `lib/hooks/`, `lib/scripts/`, or `bin/cli.js`, since `typescript` isn't enabled), the failure→misclassify→pkill sequence fires at the very start of the session — the worst possible time, before `nav_count` has any headroom to survive a stale `should_enforce: true` race outcome. This matches the reported symptom precisely: it recurs "almost every time" because the trigger condition (Serena is asked to parse a JS file in a project that hasn't enabled JS/TS) is hit on nearly every session's first few tool calls, not on rare edge cases.
|
|
44
|
+
|
|
45
|
+
8. **The reported incident text is consistent with a race that happened to land safely.** *"Serena's MCP server disconnected mid-session, so exploration fell back to Read/Bash — didn't block anything since the README/wiki already had the architecture fully synthesized"* describes a session where the kill fired, but either `should_enforce` correctly flipped to `false` (no race) or `nav_count`/prior reads had already cleared the gates, so the fallback wasn't blocked. This session's own reproduction shows the alternate (worse) outcome: the race left `should_enforce: true`, and the bash fallback *was* blocked.
|
|
46
|
+
|
|
47
|
+
## Constraints
|
|
48
|
+
|
|
49
|
+
- Any fix must preserve the hook's stated contract: **fail-open, never fail-closed** — a broken Serena must never leave the agent unable to work at all.
|
|
50
|
+
- `lib/hooks/lib/serena.js` is shared by 7+ guard hooks; changes must not regress `isAllowedPath`, symbol detection, or the message-builder API used elsewhere.
|
|
51
|
+
- The hooks are mirrored verbatim to `~/.claude/hooks/` and apply across *all* projects, not just this repo — so the classification/restart fix should be general (not bootstrap-claude-specific), while the `.serena/project.yml` language gap is this-repo-specific.
|
|
52
|
+
- No test suite currently exercises `classifySerenaFailure`/`attemptSerenaRestart` (not found via codebase search) — any fix should be validated by direct reasoning/manual reproduction, as done here, since there's no existing harness to run against.
|
|
53
|
+
|
|
54
|
+
## Recommendation
|
|
55
|
+
|
|
56
|
+
Two independent, complementary fixes — both are needed; neither alone fully resolves the symptom.
|
|
57
|
+
|
|
58
|
+
**A. Fix the hook logic (`lib/hooks/lib/serena.js`, `lib/hooks/serena-usage-tracker.js`) — applies to every project:**
|
|
59
|
+
|
|
60
|
+
1. **Stop killing a process that just answered.** A `PostToolUse`/`PostToolUseFailure` event with a parseable error payload is proof the server is alive and responsive — that is the opposite of "hung." Remove (or heavily restrict) the `pkill` branch in `attemptSerenaRestart()`; at minimum, never invoke it from `handleFailure()`'s per-tool-call error path. If a genuine "unresponsive process" signal is needed, it would have to come from the harness itself (e.g. a distinct transport-disconnect notification, or a timeout with *no* response at all) — not from a tool call that successfully round-tripped with an error.
|
|
61
|
+
2. **Flip `classifySerenaFailure()`'s default.** Change "Unknown ⇒ transport" to "Unknown ⇒ tool" (log-and-continue). A missed real transport failure just delays detection to the next failure; a false-positive under the current default is an irreversible kill. Also add the observed pattern (`cannot extract symbols`, `active languages`, `unsupported language`) to the explicit tool-level regex, since it's a deterministic, expected response.
|
|
62
|
+
3. **Make the state-file read-modify-write atomic.** `writeStateFile` currently does a bare `fs.writeFileSync` with no locking (`lib/hooks/lib/serena.js` lines 399–404), so concurrent Serena tool calls (common — agents frequently batch independent navigation calls, as this session did) race and can corrupt `error_count`/`should_enforce`, as observed. Use a write-to-temp-then-rename for atomicity, and add a short-lived lock (e.g. a `.lock` sibling file with a retry/backoff, or `proper-lockfile`) around the full read-modify-write in `handleSuccess`/`handleFailure`.
|
|
63
|
+
4. **Bound the worst case regardless.** Add a hard ceiling in `serena-first-read-guard.js`: if Gate 1 has blocked N times in a row without `warmup_done` ever succeeding, fail open rather than blocking indefinitely. This is a safety net if an unforeseen error type or another race slips past fixes 1–3.
|
|
64
|
+
|
|
65
|
+
**B. Fix this project's Serena language config (`.serena/project.yml`) — bootstrap-claude-specific:**
|
|
66
|
+
|
|
67
|
+
Add `typescript` to the `languages` list so `lib/hooks/*.js`, `lib/scripts/*.js`, and `bin/cli.js` get real symbol support instead of a guaranteed parse failure on every navigation attempt. This removes the trigger condition at its most common source for this repo and gives the agent working code intelligence for the repo's own JS surface (currently it silently degrades to Read/Bash for all JS/TS files, which the memory `hooks/serena-health-tracking` already tacitly documents but doesn't flag as a gap).
|
|
68
|
+
|
|
69
|
+
### Risks and mitigations
|
|
70
|
+
- **Risk:** Loosening the transport-classification default might mask a genuinely dead server for longer. **Mitigation:** `handleSuccess()` already restores health instantly on the next success, and the fail-open path still exists for cases where the process is *actually* absent (`isSerenaProcessAlive()` false) — only the "alive-but-erroring ⇒ kill" inversion is being removed.
|
|
71
|
+
- **Risk:** Adding `typescript` to `project.yml` spins up a TS language-server process for a repo that's primarily markdown/wiki content. **Mitigation:** this repo already ships real JS (`lib/hooks/`, `lib/scripts/`, `bin/cli.js`) that benefits from it; the overhead is the same one other projects on this machine already pay (confirmed running for `portfolio_v2` and `gauntlet/demand-letter` in `ps aux`).
|
|
72
|
+
- **Risk:** Removing the "restart" behavior entirely removes any self-healing. **Mitigation:** there was never real self-healing to begin with — the code's own comment confirms no documented mid-session stdio reconnect exists; the pkill was pure downside with no realistic upside.
|
|
73
|
+
|
|
74
|
+
### Alternative if constraints change
|
|
75
|
+
If Claude Code ever exposes a genuine transport-disconnect event (distinct from a tool-level error payload), that would be the correct signal to drive `attemptSerenaRestart()` — at that point the "kill and hope the host respawns" logic could legitimately fire on that event instead of on ordinary tool errors.
|
|
76
|
+
|
|
77
|
+
## Next Steps
|
|
78
|
+
|
|
79
|
+
- `/task-add Fix Serena health-tracking hook: stop killing live-but-erroring processes, default unknown failures to tool-level, and atomicize state-file writes (lib/hooks/lib/serena.js, lib/hooks/serena-usage-tracker.js)` — the general hook fix (A above).
|
|
80
|
+
- `/task-add Add typescript to .serena/project.yml languages list so lib/hooks/*.js, lib/scripts/*.js, and bin/cli.js get real symbol navigation` — the project-config fix (B above).
|
|
81
|
+
- Run `/wiki-ingest raw/research/serena-mcp-disconnect/index.md` to synthesize this into the knowledge base once the above tasks are filed.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: "Recent hook changes to Serena MCP health-checking appear to be causing Serena's MCP server to disconnect mid-session, almost every session"
|
|
3
|
+
slug: serena-mcp-disconnect
|
|
4
|
+
researched: 2026-07-07
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Primary Sources — Serena MCP server disconnects mid-session
|
|
8
|
+
|
|
9
|
+
| ID | Type | Locator | Accessed | What it contributed |
|
|
10
|
+
|----|------|---------|----------|---------------------|
|
|
11
|
+
| S1 | codebase | `lib/hooks/lib/serena.js` (post-`5752eed`, lines 375–510) | 2026-07-07 | `classifySerenaFailure()`, `isSerenaProcessAlive()`, `attemptSerenaRestart()`, `shouldEnforceSerena()`, state-file read/write functions — the core misclassification + kill logic |
|
|
12
|
+
| S2 | codebase | `lib/hooks/serena-usage-tracker.js` (full file) | 2026-07-07 | `handleSuccess()`/`handleFailure()` — how a Serena tool failure drives classification, restart, and fail-open; confirms unsynchronized `readStateFile → mutate → writeStateFile` |
|
|
13
|
+
| S3 | codebase | `lib/hooks/serena-first-read-guard.js` (full file) | 2026-07-07 | Gate 1 (`warmup_done`) / Gate 4 / Gate 5 logic — shows a fresh session blocks the first code `Read` until a Serena nav call succeeds, and only skips enforcement if `shouldEnforceSerena()` is false |
|
|
14
|
+
| S4 | codebase | `~/.claude/settings.json` — `hooks.PostToolUse` / `hooks.PostToolUseFailure` entries | 2026-07-07 | Confirms `serena-usage-tracker.js` is wired to both events with matcher `mcp__serena__.*\|mcp__plugin_[^_]+_serena__.*` |
|
|
15
|
+
| S5 | codebase | `.serena/project.yml` (bootstrap-claude) | 2026-07-07 | `languages: [bash, markdown, yaml]` — confirms `typescript`/`javascript` is NOT enabled for this project despite `lib/hooks/*.js`, `lib/scripts/*.js`, `bin/cli.js` being real JS code |
|
|
16
|
+
| S6 | codebase (live reproduction) | `mcp__serena__get_symbols_overview` tool_response, this session | 2026-07-07 | Verbatim error: `ValueError: Cannot extract symbols from file lib/hooks/lib/serena.js. Active languages: ['bash', 'markdown', 'yaml']` — the exact trigger, reproduced 3× in parallel against `lib/hooks/lib/serena.js`, `lib/hooks/serena-session-reset.js`, `lib/hooks/serena-usage-tracker.js` |
|
|
17
|
+
| S7 | tool output (live reproduction) | System reminder immediately following S6, this session | 2026-07-07 | `"The following MCP servers have disconnected: serena"` and the full list of `mcp__serena__*` tools becoming unavailable — the disconnect event itself, observed in real time right after the ValueError batch |
|
|
18
|
+
| S8 | shell (live reproduction) | `ps aux \| grep -i serena` output, this session | 2026-07-07 | No `serena start-mcp-server ... /Users/davidtaylor/Repositories/bootstrap-claude` process present; sibling processes `... /Users/davidtaylor/Repositories/portfolio_v2` and `... /Users/davidtaylor/Repositories/gauntlet/demand-letter` are alive and running — proves the kill was scoped to exactly this project, not a global outage |
|
|
19
|
+
| S9 | filesystem (live reproduction) | `~/.claude/state/lsp-ready-6d7a97f1dd99` (md5 of `/Users/davidtaylor/Repositories/bootstrap-claude`, first 12 hex chars) | 2026-07-07 | `health.last_error` matches S6 verbatim; `health.healthy: false`; `health.error_count: 2` (not 3 — a lost write); `health.should_enforce: true` — the inconsistent post-race state that re-armed enforcement despite the process being dead |
|
|
20
|
+
| S10 | codebase | `lib/hooks/serena-session-reset.js` (full file) | 2026-07-07 | `SessionStart` hook wipes the per-project state file (`nav_count`/`warmup_done` reset to zero) every new session — the reason Gate 1 is live at the very start of every session, when the first-file-is-JS trigger is most likely to fire |
|
|
21
|
+
| S11 | codebase | `git log --oneline -20 -- lib/hooks/` and `git show --stat 5752eed` | 2026-07-07 | Confirms commit `5752eed` ("Add Serena health tracking with fail-open enforcement, project-scoped guards, and hook consolidation", 2026-07-06) is the commit that introduced the health-tracking/restart machinery being investigated |
|
|
22
|
+
| S12 | Auto Memory | `hooks/serena-health-tracking` memory file | 2026-07-07 | Corroborates the design intent and self-acknowledged limitation: *"There is NO documented way to reconnect a stdio MCP server mid-session; 'restart' is best-effort only. Fail-open + success-based recovery is the guaranteed path."* — confirms the author already knew restarts can't truly succeed, which sharpens why triggering the kill on a false premise is the critical defect |
|
|
23
|
+
|
|
24
|
+
## Excerpts
|
|
25
|
+
|
|
26
|
+
### S1 — `lib/hooks/lib/serena.js`
|
|
27
|
+
`/Users/davidtaylor/Repositories/bootstrap-claude/lib/hooks/lib/serena.js` (lines 449–509)
|
|
28
|
+
> ```
|
|
29
|
+
> function classifySerenaFailure(errorPayload) {
|
|
30
|
+
> ...
|
|
31
|
+
> // Unknown ⇒ transport (assess health rather than silently ignore).
|
|
32
|
+
> return 'transport';
|
|
33
|
+
> }
|
|
34
|
+
> ...
|
|
35
|
+
> /**
|
|
36
|
+
> * Best-effort restart of a hung Serena server for `projectDir`: if a process
|
|
37
|
+
> * exists it is (presumably hung) killed, we wait ~1s, then re-probe. Returns
|
|
38
|
+
> * whether a live process remains afterwards. Never throws; budget < ~2s.
|
|
39
|
+
> * There is no documented way to reconnect a stdio MCP server mid-session, so
|
|
40
|
+
> * a successful "restart" only happens if the host respawns the process.
|
|
41
|
+
> */
|
|
42
|
+
> function attemptSerenaRestart(projectDir) {
|
|
43
|
+
> try {
|
|
44
|
+
> if (isSerenaProcessAlive(projectDir)) {
|
|
45
|
+
> try { execSync(`pkill -f '${serenaProcPattern(projectDir)}'`, { stdio: 'pipe' }); } catch {}
|
|
46
|
+
> try { execSync('sleep 1'); } catch {}
|
|
47
|
+
> }
|
|
48
|
+
> return isSerenaProcessAlive(projectDir);
|
|
49
|
+
> } catch {
|
|
50
|
+
> return false;
|
|
51
|
+
> }
|
|
52
|
+
> }
|
|
53
|
+
> ```
|
|
54
|
+
|
|
55
|
+
### S6 — Live reproduction: the ValueError trigger
|
|
56
|
+
Tool result from `mcp__serena__get_symbols_overview` on `lib/hooks/lib/serena.js`, this session, 2026-07-07
|
|
57
|
+
> `Error executing tool get_symbols_overview: ValueError: Cannot extract symbols from file lib/hooks/lib/serena.js. Active languages: ['bash', 'markdown', 'yaml']`
|
|
58
|
+
|
|
59
|
+
### S7 — Live reproduction: the disconnect notice
|
|
60
|
+
System reminder, this session, immediately after S6, 2026-07-07
|
|
61
|
+
> "The following MCP servers have disconnected. Their instructions above no longer apply: serena"
|
|
62
|
+
> "The following deferred tools are no longer available (their MCP server disconnected). Do not search for them — ToolSearch will return no match: mcp__serena__..." (full tool list)
|
|
63
|
+
|
|
64
|
+
### S8 — Live reproduction: process list
|
|
65
|
+
`ps aux | grep -i serena | grep -v grep`, this session, 2026-07-07
|
|
66
|
+
> ```
|
|
67
|
+
> ...python .../bin/serena start-mcp-server --context claude-code --project /Users/davidtaylor/Repositories/portfolio_v2
|
|
68
|
+
> ...python .../bin/serena start-mcp-server --context claude-code --project /Users/davidtaylor/Repositories/gauntlet/demand-letter
|
|
69
|
+
> ```
|
|
70
|
+
> (No entry for `/Users/davidtaylor/Repositories/bootstrap-claude`.)
|
|
71
|
+
|
|
72
|
+
### S9 — Live reproduction: corrupted health state
|
|
73
|
+
`~/.claude/state/lsp-ready-6d7a97f1dd99`, read this session, 2026-07-07
|
|
74
|
+
> ```json
|
|
75
|
+
> "health": {
|
|
76
|
+
> "should_enforce": true,
|
|
77
|
+
> "healthy": false,
|
|
78
|
+
> "error_count": 2,
|
|
79
|
+
> "last_error": "Error executing tool get_symbols_overview: ValueError: Cannot extract symbols from file lib/hooks/serena-usage-tracker.js. Active languages: ['bash', 'markdown', 'yaml']",
|
|
80
|
+
> "last_check": 1783446017493,
|
|
81
|
+
> "notified": false
|
|
82
|
+
> }
|
|
83
|
+
> ```
|
|
84
|
+
|
|
85
|
+
### S12 — Auto Memory: `hooks/serena-health-tracking`
|
|
86
|
+
`~/.claude/projects/-Users-davidtaylor-Repositories-bootstrap-claude/memory/hooks_serena-health-tracking.md` (read via `mcp__serena__read_memory`), 2026-07-07
|
|
87
|
+
> "There is NO documented way to reconnect a stdio MCP server mid-session; 'restart' is best-effort only. Fail-open + success-based recovery is the guaranteed path."
|