docs: refonte documentaire en 4 vagues (BROUILLON — relecture par lots)#1593
Draft
cyberlife-coder wants to merge 9 commits into
Draft
docs: refonte documentaire en 4 vagues (BROUILLON — relecture par lots)#1593cyberlife-coder wants to merge 9 commits into
cyberlife-coder wants to merge 9 commits into
Conversation
Travail produit par la campagne documentaire en 4 vagues avec verification adversariale, puis remediation ciblee. Etat : les gates du depot passent (check-doc-contract.sh et check-promise-contract.py sortent en 0), mais le critique de completude a laisse des points ouverts documentes dans la PR. Pousse pour revue, PAS pour merge immediat.
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 0 |
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
Adds 33 topic guides under docs/guides/ covering the core API surface, the Python, WASM, Node, mobile and Tauri bindings, plus runnable examples/ directories for tauri-plugin-velesdb, velesdb-mobile, velesdb-server and velesdb-wasm. Also ships the two Codex lifecycle hooks (session-start, stop) with their shared library, and refreshes the crate READMEs to point at the new guides. The guides are not yet listed in docs/guides/README.md; that index pass lands next, together with the crate README rewrites that still need the promise contract reconciled.
The 33 guides added in wave 4 were reachable only from their own crate README, so nothing under docs/ listed them: the guides index still described the pre-refactor documentation set. Rather than extend a flat 30-row table to 57, group it by the surface each guide documents — core engine, agent memory, CLI, server, Python, WASM, Node, mobile, Tauri, data migration, version migrations. All 55 guides are now listed and every link resolves. docs/README.md keeps its curated shortlist, but gains a per-binding reference table: a reader landing there previously found no entry point at all for the Python, WASM, Node or mobile APIs.
…umbers The README rewrite (844 -> 229 lines) dropped "Blazing Fast" and "ColumnStore filtering", both pinned by docs/reference/promise-contract.json, so the promise-contract gate went red. It dropped the numbers with them: 450µs p50 and 130x appeared nowhere in the new file. Losing the marketing adjective is a fair editorial call. Losing the measured claim is not — both entries carry a validation_command, so they are promises adossed to a benchmark, not slogans. Add a short Performance section carrying both claims with their measurement context and reproduction commands, and repoint the contract at the numbers (450µs p50, 130x) instead of the adjectives. A contract that pins a figure is falsifiable by the benchmark it already cites; one that pins a superlative only forces the README to keep a tone. Also fix a claim in velesdb-memory that became false in this same branch: the Codex row still said no lifecycle hook was implemented, while integrations/agent-hooks/codex/hooks/ now ships SessionStart and Stop.
Four snippets told readers to depend on velesdb-core 3.2 or 1.18 while the workspace is on 4.0.0, and one pointed at the velesdb-memory v0.11.0 tag instead of v0.11.1. A pin that contradicts the manifests is a broken copy-paste for whoever follows it. The versions guard was running in --mode warn precisely because of these five, with a comment asking that it be flipped in the same commit that fixes them. Doing that here: it is now strict, so the next stale pin turns CI red instead of adding an annotation nobody reads.
Two problems, both left by the documentation refactor. docs/guides/CLI_REPL.md described a command surface the CLI no longer has: five of its nine subcommands were regrouped under `collection`/`data` or removed outright, `-v`/`-q` never existed, four of the seven `\set` keys it documents are silently ignored, and its entire "Rust Implementation" section describes types the crate has never contained. Its accurate content is already covered by CLI_COMMAND_REFERENCE, CLI_REPL_REFERENCE, CLI_VELESQL_COOKBOOK and CONFIGURATION, so it is archived following the repository convention: file under docs/archive/ with an archive notice, a redirect stub left at the old path, a row in the archive index. The second problem is that the refactor moved or restyled several surfaces the version gate reads, without telling the gate: - the /health, /ready and /not_ready response bodies were dropped when the REST surface moved out of the server README, so the reader raised "no snippet" rather than reporting drift. Restored in SERVER_REST_TOUR.md, where the endpoints now live, and the target follows them there. - the Python README badge and the BENCHMARKS/VELESQL_SPEC stamps were replaced by the canonical `Applies to: velesdb-core X.Y.Z` footer that 60 other documents now carry. Rather than push three files back to formats nothing else uses, add an `applies_to_stamp` reader and writer and point them at it. It is anchored on `velesdb-core` because VELESQL_SPEC names the VelesQL grammar version on the same line. - CLI_REPL.md was itself a version target under two readers, one of which parsed example outputs that no longer exist; both entries and the now-dead reader are removed. check-version-sync.py and bump_version.py are kept in lock-step, verified by bumping a scratch copy to 9.9.9 and confirming all three targets moved.
Both crates now pull their own README into the crate documentation with
`#![doc = include_str!("../README.md")]`, and CI type-checks the result for
velesdb-server as well as velesdb-core.
The point is not presentation. It means a ```rust block in either README is
compiled by `cargo test --doc`, so a snippet that stops matching the API
fails the build instead of rotting in place -- which is how the CLI guide
archived two commits ago ended up describing five subcommands that no
longer exist. Blocks that must not run carry an explicit rustdoc attribute
(`rust,no_run`, `rust,ignore`); `bash`, `json` and `toml` blocks are never
compiled.
Also rewrites the velesdb-migrate README to the shared template and adds
the three Tauri example `src-tauri` sources that complete the examples/
directories shipped with wave 4.
Verified: `cargo test --doc -p velesdb-core -p velesdb-server` -- 51 passed,
0 failed.
This was referenced Jul 25, 2026
Quatre README en conflit, tous en prose écrite à la main. La branche
restructure, develop apporte du contenu neuf : le contenu neuf est conservé,
reformulé dans la nouvelle structure quand la section d'accueil avait disparu.
- integrations/agent-hooks/README.md : la correction de develop (quatre hooks
Claude Code, deux Codex, un Windsurf, PreCompact non câblé) est déjà portée,
en plus détaillé, par le tableau de parité de la branche. Rien perdu.
- crates/velesdb-node/README.md : les deux sections neuves de develop
("What you actually gain", "How it works, in four steps") sont conservées
intégralement, placées après Objective, devant les sections de la branche.
- crates/velesdb-memory/README.md : mêmes deux sections neuves replacées dans
la version restructurée (1616 → 322 lignes). Le renvoi "the PostToolUse hook,
below" pointait vers une section supprimée par la restructuration : il cible
désormais integrations/agent-hooks/README.md.
- README.md : section neuve "How it works, in plain terms" conservée. Son
ancre #the-numbers--every-one-from-a-committed-harness ne survivait pas à la
restructuration ; retargetée sur #proof--three-numbers-each-tied-to-its-harness.
Trois contradictions que git ne signale pas, parce que les fichiers concernés
s'auto-fusionnent proprement :
1. docs/reference/promise-contract.json épingle "~10 MB binary" et
"~674 KB gzipped" (valeurs re-mesurées le 2026-07-25 sur les artefacts
réels) tandis que les README de la branche disaient encore ~9 MB et
~550 KB. Quatre occurrences corrigées : le merge était déclaré propre par
git et check-promise-contract.py serait passé au rouge derrière.
2. develop ajoute check_provenance() à scripts/check-promise-contract.py, qui
exige measured_on / measured_machine / measured_version sur CHAQUE claim ;
la branche ajoute de son côté la claim core_readme_columnstore_speedup, née
sans ces champs. Les deux fichiers fusionnent sans conflit et le gate tombe.
Provenance renseignée en miroir de readme_columnstore_130x_claim : même
bench, même chiffre, mêmes conditions — pas une mesure inventée.
3. Le README racine perd 168 lignes : vérifié route par route que
l'amputation n'a fait disparaître aucune route documentée. 30/34 routes
documentées avant comme après, mêmes 4 manquantes qu'aujourd'hui sur
develop (compact, points/raw, stream/enable, vacuum), et les deux routes
bloquantes /query/explain et /aggregate sont présentes.
Gates rejoués, verts : check-doc-contract.sh, check-promise-contract.py,
check-version-sync.py.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ce que c'est
Campagne documentaire menée en 4 vagues par une équipe d'agents indépendants, avec un checker adversarial par vague et un critique de complétude final, puis une passe de remédiation ciblée de 7 agents.
Volume produit : le gabarit
.github/DOC_TEMPLATE_CRATE.md, les 3 READMEs de crates Premium qui manquaient,docs/GETTING_STARTED.md(fusion de 5 documents), le dossierdocs/deployment/, 5 guides OSS, un guard de fraîcheur, l'indexdocs/README.mdrendu exhaustif.Ce qui est vérifié
Les gates du dépôt passent, exécutés sans pipe (le pipe masque le code de sortie — erreur commise trois fois dans cette campagne) :
sync_versions.py --checkonboarding_contract_tests.pyrelease_surface_version_tests.pyquality_gates_contract_tests.pyproduct_truth_contract_tests.pycheck-doc-contract.sh/check-promise-contract.pyCe qui reste ouvert — la raison du brouillon
Le critique de complétude a rendu non mergeable sur la première passe. La remédiation a soldé les 6 blocages, mais des réserves demeurent :
CORE_PREMIUM_SPLITentre dépôts (qui s'avère être un lien mort, pas un doublon),STORAGE_RELOCATION_CONTAINMENTvs_PROTOCOL,SECURITY.mdvsSECURITY_CONFIGURATION_THREAT_MODEL, absence de guide de migration 4.0.0,setup-hooks.shmanquant face àsetup-hooks.ps1, statut develesdb-mobile, Devin/Cognition comme cible, audience des installeurs natifs.docs/reference/promise-contract.json, qui épingle 24 sous-chaînes verbatim. Un avertissement a été ajouté en tête.Ma recommandation
Relire par lots plutôt qu'en bloc : d'abord les 3 READMEs de crates (nouveaux, autonomes, faible risque), puis
GETTING_STARTED.md(1249 lignes issues d'une fusion — c'est là que la perte de contenu serait grave), enfin le README racine OSS.