Repository navigation
Technical Wiki and AI
Audience: maintainers of the documentation and AI knowledge base. Baseline reviewed: 2026-10-29.
Basic guides and technical knowledge both live in the AVideo wiki checkout. Local organization is:
AVideo.wiki/
Home.md
User-manual.md
Plugin-Documentation-Index.md
technical/
Technical-Documentation.md
Technical-Architecture.md
Technical-Plugin-Index.md
plugins/
Technical-Plugin-Live.md
Technical-Plugin-VideoThumbnails.md
reference/
Technical-Reference-Objects-01.md
tools/
build_reference.py
extract.php
plugin-notes.json
source-manifest.json
GitHub Wiki uses page filenames/titles rather than the repository-style directory tree. Every technical page has a unique Technical- basename. Internal links point to canonical wiki page URLs without a filesystem subdirectory or .md extension. Repeated filenames such as several README.md files would be ambiguous and are avoided.
Use the technical index for technical navigation and retain the existing user-facing sidebar groups. The general wiki page list can still contain technical pages; folders are organizational, not access restrictions or a mechanism for hiding pages.
Pages become public/live only after the relevant wiki changes are committed and pushed to its default branch, as described by GitHub's wiki documentation. GitHub's wiki grouping discussion describes the navigation limitation. Public rendering of these newly created pages cannot be verified before publication.
The reviewed AIAgent ingestion implementation supports .md, .markdown and .pdf. Its document discovery uses recursive glob patterns, so technical Markdown in subdirectories is discovered when the wiki is the configured document tree. _Sidebar, _Footer and _Header are navigation fragments and are not indexed. Loading this content does not require putting documents into the AVideo application repository.
Markdown is split along its headings, and every chunk starts with its page name and heading path, so a row of a long reference table keeps the plugin and section it belongs to. Long table fragments repeat their column headers. Fenced code examples do not create headings or page metadata. Relative wiki links are stored as absolute wiki URLs.
Each Markdown chunk records the unique page name and its wiki URL (without the local subfolder), the first # title, and a category derived from the page name:
| Category | Pages |
|---|---|
| Basic guide | Pages without the Technical- prefix |
| Technical explanation |
Technical-* pages, including the plugin and reference indexes |
| Technical plugin reference |
Technical-Plugin-<Name> pages |
| Generated source inventory |
Technical-Reference-* pages, except the index |
The Audience:, review date, reported plugin version and code ownership lines are recorded only when the page states them; nothing is inferred for pages that do not. PDFs are recorded by file name and page number and have no wiki URL. The agent's search tool can be limited to basic guides (with the PDFs), technical pages or source inventories; it searches everything by default.
Scoped retrieval fetches all vector candidates before filtering categories, so guides cannot disappear just because many source-inventory chunks rank first. Search output reports squared L2 distance (lower is closer); it does not enforce a relevance threshold or prove that an excerpt answers the question.
Incremental ingestion replaces changed files, removes deleted/orphan chunks, and re-embeds legacy chunks with missing/random IDs or inconsistent counts. It loads and scans the existing index even when no file changed. IDs currently use absolute paths: moving the document directory or changing between Windows and Linux re-embeds files and replaces the old identities.
New index writes atomically replace a single index.snapshot containing vectors, metadata and their mapping. Legacy index.faiss/index.pkl pairs remain readable and are preserved during migration. Deploy the updated readers before authorizing ingestion; older code cannot read the new format. Snapshot and manifest are separate atomic writes, in that order. A manifest-write failure is reported and reconciled on a subsequent run; multiple ingestion writers must be serialized externally. Parsing or embedding failure, including a partial rebuild, preserves the previous storage. An empty document tree is an error and does not silently erase the knowledge base.
The running agent checks storage signatures and reloads changed snapshots without a restart. If a replacement is corrupt, an already loaded copy remains usable; a cold process reports an unavailable knowledge base. A Windows file-sharing violation fails replacement while retaining the previous snapshot. These serialized files must come from trusted local storage.
The effective backend/system_prompt.txt is copied into the image at build time and read once when the agent starts. Applying a prompt change requires an image rebuild and backend recreation; restarting the old image or running ingestion alone does not copy the changed prompt. system_prompt.example.txt is only the fallback for a missing/unreadable effective file. Building an image does not run ingestion, but backend recreation runs its entrypoint and can call the embedding provider.
The primary wiki checkout and the agent's data/docs clone are separate trees. Publish reviewed wiki changes, then synchronize the ingestion clone while preserving deployment-only PDFs, before authorizing reindexing. Editing this page does not perform any of those operations.
Tools, JSON manifests and source code are maintenance artifacts rather than Markdown knowledge pages. Their presence does not mean the loader interprets them or follows their source links. Keep these page conventions stable (unique Technical- names, a # title, an Audience: line and the Source baseline list on plugin pages): the loader reads them.
For ordinary support, prefer interface steps and expected behavior from basic guides. Use technical references to explain dependencies, investigate failures and verify exact symbols/configuration. Preserve the distinction between source evidence, an inference and a real integration-test result.
Test representative questions after a separately authorized ingestion: ordinary setup, troubleshooting across components, plugin-version differences and questions whose answer is genuinely absent. Check retrieval and source attribution as well as the final wording.
Creating these wiki files does not run production ingestion, change its configuration or update a deployed index. Confirm the deployed checkout/mount, update strategy and ingestion result when that work is authorized.
