From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Sat, 26 Sep 2026 20:04:37 +0000 (+0300)
Subject: docs: sync Development page with source, modernize conventions
X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=277cc0b877cb518d56c37ae7cee42b758edeb572;p=retinue.git

docs: sync Development page with source, modernize conventions

- fix retinue_memory_search schema block: limit default 10 -> 50 and
  descriptions synced with src/retinue/provider.py
- correct "cosine-similarity search" to KNN by L2 distance (vec0
  default), matching the retrieval section
- sync project-structure tree with the actual repo (import_holographic.py,
  system_prompt_block.txt, test/, Tools/lib, Open with IntelliJ IDEA,
  Development/index.org itself)
- add file-level drawer (:ID: + :CUSTOM_ID: development) and switch the
  back-link to the exported-anchor form
  (../index.html#outline-container-development)
- AGENTS.org: document the anchor back-link and file-level CUSTOM_ID
  conventions for sub-pages
---

diff --git a/AGENTS.org b/AGENTS.org
index 06d5147..35652a9 100644
--- a/AGENTS.org
+++ b/AGENTS.org
@@ -85,8 +85,12 @@ virtual table =memories=).
   UUID (and a kebab-case =:CUSTOM_ID:= matching the heading text for
   in-page anchors). Generate UUIDs with
   =python3 -c "import uuid; print(uuid.uuid4())"=.
-- Cross-page links use =[[file:...]]=, e.g. =[[file:Development/][Development]]=
- and =[[file:../index.org][Back to main documentation]]=.
+- Cross-page links use =[[file:...]]=, e.g. =[[file:Development/][Development]]=.
+  Sub-pages open with a back-link to the parent's exported HTML anchor:
+  =[[file:../index.html#outline-container-development][<- Back to index]]=.
+  Sub-pages also carry =:CUSTOM_ID: <section>= in the file-level drawer as
+  the page's identity marker (it does not export an HTML anchor; a page's
+  real link targets are its heading CUSTOM_IDs).
 - Org tables need a =|----+----|= separator row between header and data,
   and a trailing =|= on every row.
 - Options line is exactly:
diff --git a/Documentation/Development/index.org b/Documentation/Development/index.org
index d2e1b08..1e35428 100644
--- a/Documentation/Development/index.org
+++ b/Documentation/Development/index.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       15243585-3ec1-467a-be81-981fa7e5807f
+:CUSTOM_ID: development
+:END:
 #+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme
 #+TITLE: Development - Retinue
 #+LANGUAGE: en
@@ -8,7 +12,7 @@
 #+OPTIONS: H:20 num:20
 #+OPTIONS: author:nil
 
-[[file:../index.org][Back to main documentation]]
+[[file:../index.html#outline-container-development][<- Back to index]]
 
 * Architecture
 :PROPERTIES:
@@ -50,7 +54,8 @@ $HERMES_HOME/retinue_memory.db
 
 =MODEL_DIM= depends on the model (hardcoded to
 =minishlab/potion-multilingual-128M=). The table is created with
-=sqlite-vec= and supports cosine-similarity search.
+=sqlite-vec= and supports KNN vector search by L2 distance (the =vec0=
+default).
 
 Why a /virtual/ table? In SQLite, a virtual table is created with
 =CREATE VIRTUAL TABLE ... USING vec0(...)=. The =vec0= module from
@@ -69,20 +74,27 @@ the =sqlite-vec= extension.
 #+begin_src
 Retinue/
 ├── Documentation/
-│   └── index.org             # This file
+│   ├── index.org             # Public user documentation
+│   └── Development/index.org # This file
 ├── Install Retinue           # Deploy into the active Hermes plugin directory
 ├── plugin.yaml               # Hermes plugin metadata
 ├── __init__.py               # Plugin entry point: register(ctx)
 ├── src/                      # Plugin source package
 │   └── retinue/
 │       ├── __init__.py       # Package init
-│       ├── memory.py        # Memory engine: embeddings + sqlite-vec
-│       ├── provider.py      # MemoryProvider subclass
-│       └── cli.py           # Debug CLI behind "Show Retinue memory contents"
+│       ├── memory.py         # Memory engine: embeddings + sqlite-vec
+│       ├── provider.py       # MemoryProvider subclass
+│       ├── cli.py            # Debug CLI behind "Show Retinue memory contents"
+│       ├── import_holographic.py  # Holographic memory_store.db importer
+│       └── system_prompt_block.txt # Injected into the Hermes system prompt
+├── test/
+│   └── test_standalone.py    # End-to-end MemoryStore + provider tests
 ├── Tools/                    # Development helpers (desktop scripts)
+│   ├── lib/common.sh         # Shared bash helpers: RETINUE_PY resolution
 │   ├── Run tests            # Standalone smoke test runner
 │   ├── Show Retinue memory contents  # Debug CLI: dump/search all memories
 │   ├── Import Holographic memories   # Migrate facts from Holographic memory_store.db
+│   ├── Open with IntelliJ IDEA
 │   └── Update web site      # Export Documentation/*.org to HTML + publish
 └── $HERMES_HOME/retinue_memory.db    # Created at runtime: SQLite + sqlite-vec
 #+end_src
@@ -192,12 +204,12 @@ Semantic search across all memories.
 #+begin_src json
 {
   "name": "retinue_memory_search",
-  "description": "Search Retinue memories by semantic similarity.",
+  "description": "Search Retinue memories by semantic similarity. Use when you need to recall relevant context even if the user uses different wording than the stored memory.",
   "parameters": {
     "type": "object",
     "properties": {
-      "query": {"type": "string", "description": "Natural-language search query"},
-      "limit": {"type": "integer", "default": 10}
+      "query": {"type": "string", "description": "Natural-language search query."},
+      "limit": {"type": "integer", "description": "Maximum number of results to return.", "default": 50}
     },
     "required": ["query"]
   }