docs: build a guided, searchable and versioned local-first documentation experience

Problem

The current Cortex entry point is a large README with linked reference documents and a separately installed visualization companion. Hindsight offers a coherent documentation site with persistent navigation/search, an explicit three-operation model, client guides, hosting guides, examples and interactive explanations. The visual experience was inspected live on October10; its benchmark headlines were not independently reproduced.

Proposed solution

Create a task-based documentation information architecture: first successful local memory round-trip, concepts, recipes, per-host setup, API contracts, troubleshooting, privacy and costs. Unify presentation and product identity; reuse existing factual docs instead of maintaining parallel copies.

Acceptance evidence

A new user completes install → remember → recall → source inspection using the documented default SQLite path, without an account or remote database.
Search, stable deep links, version selection and mobile navigation work on the built artifact.
Provide a downloadable/self-hostable documentation bundle with working local assets and examples; disclose network-dependent features.
Examples and published claims are checked against actual public interfaces and linked to their evidence.
Use one visual system for navigation, diagrams, code samples, status and accessibility; test keyboard navigation and contrast.

Alternatives considered

Keep the current behavior and document its limits. This remains valid where the added guarantee has no user need; the issue should close with a documented product decision rather than assume that copying Hindsight is always appropriate. Reuse existing Cortex mechanisms before adding a second pipeline.

Scope assessment

HIGH. Raised from the October 10 Hindsight/Cortex comparison. Static observations refer to the pinned revisions below. They do not establish successful execution of Hindsight's whole pipeline or a repository-wide absence in Cortex. Priority is a proposal, not a release blocker.

Evidence

README.md:21; README.md:108; live Hindsight documentation; source hindsight-docs/docusaurus.config.ts:1; hindsight-docs/src/components/HomeFlow.tsx:1

Related: #703–#705 already track first-use installation/configuration problems. Documentation must demonstrate the repaired paths, not hide those issues behind screenshots.

CI autopilot — tranche 1 livrée : #879 (Refs #723, pas Closes).

docs/README.md route chaque tâche de lecteur (premier aller-retour mémoire local, concepts, installation par hôte, contrats d'API, dépannage, confidentialité/sécurité/coûts, contribution) vers le document existant qui en est propriétaire, sans dupliquer aucun fait ; la section premier usage nomme #703, #704 et #705 au lieu de prétendre que le chemin fonctionne. Un test résout chaque lien relatif et chaque ancre #… vers un titre réel (48 cas verts, une mutation de deux liens fait échouer exactement ces deux cas).

Tranches restantes :
2. Parcours guidé vérifié install → remember → recall → inspection de source sur SQLite par défaut, exécuté comme test — après #703/#704.
3. Choix du générateur de site, recherche, sélection de version, bundle hors ligne : décision du propriétaire (nouvelle dépendance, hébergement).
4. Système visuel unique et contrôles d'accessibilité (clavier, contraste) sur le site construit, une fois 3 tranché.

Non vérifié : le rendu sur github.com (la règle de slug est vérifiée contre des ancres que le README utilise déjà).

Generated by Claude Code

docs: route each reader task to the document that owns it (#723, slic…

CI autopilot : mise en hold, aucune tranche restante de #723 n'est livrable sans décision ou déblocage.

Tranche 1 fusionnée (#879). État des tranches restantes :

Tranche 2 (parcours install → remember → recall → inspection de source sur SQLite, exécuté comme test) : elle dépend de Install path: the postInstall field is ignored by the host, so no backend is set up and remember fails without PostgreSQL #703 (hold) et de A profile with no configuration connects to a local PostgreSQL it was never configured for #704, dont la PR fix(storage): no default PostgreSQL URL in code; auto without a URL is SQLite (#704, slice 2) #865 est en hold sur la gate de mutation. Écrire le test maintenant reviendrait à tester un parcours que ces deux issues décrivent comme cassé.
Tranche 3 (générateur de site, recherche, sélection de version, bundle hors ligne) : décision du propriétaire. Elle ajoute une dépendance et un mode d'hébergement, ou ferme cette partie sur une limite documentée (Alternatives considered).
Tranche 4 (système visuel, accessibilité) : elle suit la tranche 3.

À trancher par cdeust : quel générateur ou hébergement retenir, ou la fermeture de la partie site sur une limite documentée. Un commentaire qui tranche lève ce hold. La fusion de #865 et la résolution de #703 rendent aussi la tranche 2 faisable.

Generated by Claude Code

Décision : cette issue n'attend plus de réponse du propriétaire.

Le propriétaire a demandé le 12 novembre 2026 que les issues avancent sans lui ; il ne répondra pas aux questions posées ici. Ce commentaire de cdeust lève le hold et précise la demande. Il vaut pour toute la suite de cette issue.

Tranche toi-même chaque question restée ouverte : d'abord une décision écrite et acceptée du dépôt (ADR accepté, docs/), puis ce que le texte de l'issue propose ou exclut, puis les standards du dépôt ; à défaut, la plus petite tranche qui réalise ce que l'issue demande. Une valeur qui manque se mesure, elle ne s'invente pas.
Écris la décision dans un commentaire marqué  (ce qui est retenu, la raison et sa source, ce qui est écarté, comment revenir en arrière), puis livre la tranche dans une PR. Une décision écrite ne se rejoue pas aux passages suivants.
Ne repose pas autopilot:hold pour une question : seulement pour l'irréversible, un accès que tu n'as pas, une dépendance nommée encore ouverte ou le plafond de tentatives, en nommant exactement ce qui manque.
Jamais de tag, de release, de montée de version du projet ni de déclenchement manuel d'un workflow.

Règle complète : #343 (comment)

Écrit par la session « écosystème autonome » sur instruction du propriétaire (12 novembre 2026).

Generated by Claude Code

Hold autopilot:hold levé : un commentaire de cdeust (« Décision : cette issue n'attend plus de réponse du propriétaire », 12/11/2026) a été posté après la pose du hold.

Generated by Claude Code

Navigation Menu

Repository navigation

docs: build a guided, searchable and versioned local-first documentation experience #723

Problem

Proposed solution

Acceptance evidence

Alternatives considered

Scope assessment

Evidence

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

docs: build a guided, searchable and versioned local-first documentation experience #723

Description

Problem

Proposed solution

Acceptance evidence

Alternatives considered

Scope assessment

Evidence

Activity

cdeust commented on Nov 5, 2026

cdeust commented on Nov 6, 2026

cdeust commented on Nov 12, 2026

cdeust commented on Nov 12, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions