# WikiStub-Seed
**EN** | [DE](README_de.md) | [ES](README_es.md) | [JA](README_ja.md) | [RU](README_ru.md) | [ZH](README_zh-Hans.md)
**WikiStub-Seed is a general-purpose, multilingual JSON knowledge-stub framework: a starter scaffold for any topic, not limited to AI workflows.** It ships 630 compact knowledge stubs across 12 scientific and cultural domains, ready for research, documentation, learning systems, wikis, or AI/LLM workflows alike. Definitions are populated in DE/EN/ES/ZH/JA/RU; relevance notes are populated in DE/ES/ZH/JA/RU and use the documented German fallback for the currently empty English relevance slots.
WikiStub-Seed is a knowledge-stub seed library, not a wiki.
[](https://github.com/dev-bricks/WikiStub-Seed/actions/workflows/tests.yml)
[](pyproject.toml)
[](https://github.com/dev-bricks)
[](https://github.com/open-bricks)
[](https://github.com/astral-sh/ruff)
[](NOTICE)
[](MARKETING-LOG.txt)
[](llms.txt)
### Quick Navigation
- [1. Executive Summary & Core Identity](#1-executive-summary--core-identity)
- [2. Visual Architecture & System Topology](#2-visual-architecture--system-topology)
- [3. Local Workflow & Query Sequence Flow](#3-zero-egress-lifecycle--query-sequence-flow)
- [4. Target Personas & Discoverability Queries](#4-target-personas--discoverability-queries)
- [5. Comparative Matrix vs. Alternatives](#5-comparative-matrix-vs-alternatives)
- [6. Runtime Behavior and Evidence Notes](#6-governance--runtime-invariants-matrix)
- [7. Installation & Quick Start](#7-installation--quick-start)
- [8. Local Edit Mode & HTTP Server (127.0.0.1)](#8-local-edit-mode--http-server-127001)
- [9. Core Commands & CLI Operations](#9-core-commands--cli-operations)
- [10. Repository Map & Key Assets](#10-repository-map--key-assets)
- [11. Data Shape & Knowledge Schema](#11-data-shape--knowledge-schema)
- [12. Sibling Tools & Ecosystem Matrix](#12-sibling-tools--ecosystem-matrix)
- [13. Third-Party License References & Scope](#13-third-party-licenses--level-1-sbom)
- [14. Security Policy & Response Targets](#14-security-policy--operational-limits-48h-sla)
- [15. Static PWA & Web Publisher Architecture](#15-static-pwa--web-publisher-architecture)
- [16. Testing, Verification & CI Matrix](#16-testing-verification--ci-matrix)
- [17. Discovery Keywords & AI Agent Index](#17-discovery-keywords--ai-agent-index)
- [18. License and Attribution](#license)
---
## 1. Executive Summary & Core Identity
| If you want to... | Open this |
|---|---|
| Inspect the dataset | `wikistub_seed.json` |
| Run a quick local check | `python wikistub_seed_cli.py check` |
| Export Markdown for docs or notes | `python wikistub_seed_pipeline.py export --output --english` |
| Understand the exchange format | `EXPORTFORMAT.md` |
| Read the optional local search contract | `EMBEDDING_SEARCH_API.md` |
| Browse the static PWA source | `web_publisher/` |
| Read AI/LLM index file | [llms.txt](llms.txt) |
| Read the German guide | [README_de.md](README_de.md) |
> [!NOTE]
> **AI & LLM Integration**: For machine-readable context, repository structure, search phrases, and LLM guidelines, see [llms.txt](llms.txt).
### Key Features
- **630 Knowledge Stubs**: Curated in `wikistub_seed.json` with definitions across 6 languages (DE, EN, ES, ZH, JA, RU) and relevance notes across 5 languages.
- **12 Top-Level Domains**: Mathematics, physics, chemistry, biology, medicine, psychology, AI/CS, engineering, society, economics, history, and culture.
- **85 Structured Subcategories**: Short, neutral definitions and practical relevance notes.
- **Source-Checkout Core**: Dataset checks, statistics, and exports use the Python standard library; optional translation, search integrations, and development checks have separate dependencies.
- **Dual Consumption Models**: Batch CLI export to structured Markdown or a static PWA reader that can cache fetched resources and dataset files.
### Use Cases
- Seed a local knowledge base for AI-assisted writing or research.
- Build documentation glossaries, learning maps or concept catalogs.
- Export structured Markdown for Obsidian, GitHub Pages or static documentation sites.
- Feed retrieval, embeddings or LLM context pipelines with compact domain stubs.
- Translate and extend a domain-neutral knowledge skeleton in a controlled JSON format.
---
## 2. Visual Architecture & System Topology
```mermaid
flowchart TD
subgraph Data_Layer["Authoritative Knowledge Layer"]
A["wikistub_seed.json
(630 Multilingual Stubs across 12 Domains)"]
end
subgraph Processing_Core["Local Processing & Tooling Core"]
B["wikistub_seed_cli.py
(Stats, Consistency & Validation)"]
C["wikistub_seed_pipeline.py
(Markdown & JSON Exporter)"]
D["web_publisher/_build.py
(Deterministic PWA Publisher)"]
end
subgraph Integration_Layer["Ecosystem & Consumer Channels"]
E["RAG & LLM Context Pipelines
(AI Workflows, Embeddings & Prompts)"]
F["Structured Markdown Trees
(Obsidian / GitHub Pages / Docs)"]
G["PWA Web Reader
(Search over 6 Dataset Languages; Cached After Fetch)"]
end
A --> B
A --> C
A --> D
A --> E
C --> F
D --> G
```
---
## 3. Local Workflow & Query Sequence Flow
```mermaid
sequenceDiagram
autonumber
actor User as Developer / AI Agent
participant CLI as wikistub_seed_cli / pipeline
participant Data as wikistub_seed.json (630 Stubs)
participant Builder as web_publisher/_build.py
participant PWA as Static PWA / ServiceWorker
User->>CLI: Run check / stats / validate
CLI->>Data: Validate 12 Domains, 85 Subcategories & Maps
Data-->>CLI: 630 stubs validated from local files
CLI-->>User: Console Report & Consistency Proof
opt Export Markdown / RAG Context
User->>CLI: export --output --english
CLI->>Data: Read definitions & relevance maps
CLI-->>User: Write structured Markdown to output/
end
opt Build & Serve Local PWA
User->>Builder: Run _build.py
Builder->>Data: Slices & indexes stubs
Builder-->>PWA: Generates data/wikistub_seed.json & search-index.json
PWA-->>User: Search cached data using the selected dataset language
end
```
---
## 4. Target Personas & Discoverability Queries
WikiStub-Seed is engineered to address four primary developer and researcher archetypes:
### `[PERSONA-01]` AI & LLM Engineers (RAG & Local Knowledge Injection)
- **Goal:** Inject high-signal, domain-curated knowledge stubs into local LLM contexts, vector stores (FAISS, Chroma, Qdrant), or agent prompts without scraping latency or noisy web HTML.
- **Pain Point:** Raw Wikipedia XML dumps and web scrapes require gigabytes of storage, complex extractors, and produce noisy wikitext boilerplate with unverified schema consistency.
- **Solution:** Deterministic `wikistub_seed.json` (630 stubs) with parallel multilingual definition maps ready for direct JSON or Markdown ingestion (`wikistub_seed_pipeline.py export`).
### `[PERSONA-02]` Domain Researchers, Curators & Ontologists
- **Goal:** Maintain a clean, cross-disciplinary concept hierarchy spanning 12 academic fields (Math, Physics, Chemistry, Biology, Medicine, CS/AI, etc.) with verified terminology.
- **Pain Point:** Enterprise ontology suites (Protégé, OWL, RDF triple stores) impose heavy infrastructure hurdles and steep learning curves for rapid knowledge curation.
- **Solution:** Human-readable JSON structure with built-in validation CLI (`wikistub_seed_cli.py check/stats`), duplicate verification, and local browser GUI (`python edit_server.py`).
### `[PERSONA-03]` Local-First Knowledge Tool Builders
- **Goal:** Build knowledge tools that work with selected local files and can reuse previously fetched web resources when available.
- **Pain Point:** Hosted dictionary and encyclopedia services may transmit queries and require service access or credentials.
- **Solution:** Local JSON workflows, a loopback edit server and a static PWA that can reuse resources after they are cached. Optional translation sends selected text and instructions to Anthropic.
### `[PERSONA-04]` Educators & Technical Documentation Specialists
- **Goal:** Rapidly generate course glossaries, foundational concept notes, and study decks for students in Markdown, Obsidian vaults, or static documentation sites.
- **Pain Point:** Manually compiling bilingual terminology definitions across dozens of disciplines takes weeks of laborious authoring.
- **Solution:** One-command batch export to categorized Markdown directory trees (`wikistub_seed_pipeline.py export --output --english`), easily imported into Obsidian, Docusaurus, or MkDocs.
### High-Intent Discovery Search Queries
| Language | Query String | Intent & Context |
|:---|:---|:---|
| **EN** | `multilingual json knowledge base` | RAG & context seeding |
| **EN** | `llm context dataset 630 stubs bilingual` | LLM prompt enrichment |
| **EN** | `rag knowledge base json python standard library` | Zero-dependency retrieval |
| **EN** | `wikipedia stub seed dataset offline` | Clean Wikipedia alternative |
| **EN** | `structured markdown export for obsidian knowledge vault` | Personal Knowledge Management |
| **EN** | `local rag json starter dataset python` | Offline RAG knowledge scaffold |
| **EN** | `multilingual offline concept stubs 12 domains` | Multi-domain taxonomy seeding |
| **DE** | `Mehrsprachige JSON Wissensbasis Python` | Lokale Begriffsdatenbank |
| **DE** | `Lokale Wissensdatenbank für RAG und LLMs` | KI-Kontextinjektion |
| **DE** | `Strukturierte Konzept-Stubs 12 Domänen` | Multidisziplinäre Ontologie |
| **DE** | `Lokale JSON Wissensverwaltung Python` | Mehrsprachige Wissens-Stubs mit optionaler externer Übersetzung |
| **DE** | `Markdown Export für Obsidian Wissensgraphen` | Offline PKM & Obsidian |
| **DE** | `Lokales RAG JSON Starter-Dataset Python` | Offline RAG Wissens-Scaffold |
| **DE** | `Mehrsprachige Offline Konzept-Stubs 12 Domänen` | Domänen-Taxonomie-Seeding |
---
## 5. Comparative Matrix vs. Alternatives
The following 10-dimension matrix compares `WikiStub-Seed` against common approaches for knowledge seeding and documentation:
| Dimension | WikiStub-Seed | Kiwix / Wikipedia Dumps | MediaWiki / DokuWiki | Raw Web Scrapes (Common Crawl) | Static Docs (Docusaurus / MkDocs) |
|:---|:---|:---|:---|:---|:---|
| **1. Runtime Footprint** | Source-checkout core commands use the Python standard library; API dependencies are listed separately | Dedicated ZIM reader | PHP / MySQL / Web server | Big Data / Spark cluster | Node.js / Python env |
| **2. Deterministic Schema (`INV-SCHEMA-03`)** | Schema-validated JSON dataset | Unstructured wikitext | Ad-hoc wiki formatting | Unstructured text noise | Ad-hoc Markdown / MDX |
| **3. Parallel Multilingual Mapping** | **6 Normalized Languages** | Separate databases | Manual interlanguage links | Unaligned / mixed | Manual i18n configuration |
| **4. RAG & LLM Ingestion Readiness** | **Direct JSON / Markdown feed** | Complex parsing required | Scraping / API required | Heavy tokenization needed | Manual indexing required |
| **5. Local processing and optional network use** | Local file operations; optional translation calls Anthropic | Offline ZIM reader | Depends on hosting | Online scraping required | Local build / Web deploy |
| **6. Unprivileged Mode (`INV-SEC-02`)** | Runs with the current process permissions | User mode | Often requires server root | N/A | User mode |
| **7. Localhost GUI Edit Server (`INV-SRV-05`)** | **Built-in `127.0.0.1` server** | Read-only | Full server CMS | None | Dev preview server |
| **8. Offline PWA Publisher** | Static PWA with a Service Worker cache after fetch | Kiwix client app | Server required | None | Custom plugin needed |
| **9. Project and dependency licenses** | MIT project license; dependency terms are listed separately | CC BY-SA (Copyleft) | GPLv2+ (Copyleft) | Complex copyright status | MIT / Apache-2.0 |
| **10. Security response** | Maintainer response targets documented in SECURITY.md | Community bug tracker | Security team tracker | None | Individual maintainers |
---
## 6. Runtime Behavior and Evidence Notes
These notes describe implemented behavior and its limits; they are not certifications or guarantees.
| Topic | Observed behavior | Evidence and limits |
|---|---|---|
| Local processing | CLI checks, exports and local editing use selected local files. Optional translation sends selected text and instructions to Anthropic when invoked with the CLI controls. | See translate.py and the command options below; no general zero-egress claim is made. |
| Process permissions | Commands run with the permissions of the process that starts them. | The project does not claim a formal RunAsInvoker certification. |
| Dataset validation | The CLI validates the dataset structure and reports consistency issues. | See wikistub_seed_cli.py check and wikistub_seed_pipeline.py validate. |
| Storage and network | Dataset and export files are local inputs and outputs; optional translation is an external request. | Network behavior depends on the selected command and optional integrations. |
| Local edit server | The optional edit server binds to loopback. | See edit_server.py; this does not describe a remotely hosted service. |
| Authentication and trash | The editor stores authentication data locally and supports soft-delete trash and restore APIs. | See wiki_auth.py, wiki_store.py, and the editor tests. |
| CI coverage | GitHub Actions tests selected Python, operating-system, source-smoke, PWA and package paths. | The configured matrix is not a claim of identical behavior across all platforms. |
| Dependency scope | Core CLI operations use the Python standard library; optional features and development checks have additional dependencies. | See pyproject.toml and the bounded notes in THIRD_PARTY_LICENSES.md. |
| Sync files | .gitignore excludes common conflict and lock-file patterns. | Ignore rules do not prevent a sync client from operating. |
| Security response | Maintainers aim for the response targets in SECURITY.md. | Targets are not guaranteed service levels. |
---
## 7. Installation & Quick Start
Use a source checkout for the full CLI, editor, dataset, and PWA. The wheel exposes six reusable API modules. Installed API calls require explicitly selected external data and authentication paths; package files are not user-data storage. Module translation APIs require an explicit max_budget_usd; the CLI additionally requires --confirm-api-cost.
```bash
git clone https://github.com/dev-bricks/WikiStub-Seed.git
cd WikiStub-Seed
python wikistub_seed_cli.py --help
python wikistub_seed_cli.py stats
python wikistub_seed_cli.py check
python wikistub_seed_pipeline.py validate
python wikistub_seed_pipeline.py export --output --english
```
On Windows, `start.bat` opens the CLI entry point. Exported files are written to `output/`; that folder is local and not versioned.
---
## 8. Local Edit Mode & HTTP Server (127.0.0.1)
`web_publisher/` is a static site (no server, `fetch()`-only) and cannot write. `edit_server.py` adds a small, `127.0.0.1`-only HTTP server on top of it so the same reader UI can create, edit and delete articles/categories:
```bash
python edit_server.py # default port 8879, opens the browser
```
**Rights model** (verbatim from the specifying request, and the one binding rule this feature follows):
- Creating new entries is allowed by default, for everyone.
- Editing and deleting are allowed for everyone **as long as no password is set**.
- Once a password is set, whoever set it decides what an anonymous visitor may still do — anywhere from "everything" down to read-only (create/edit/delete are independently revocable via the "Konto" panel in the header).
- There is deliberately only **one** password/role. Multiple tokens with different rights plus an administrator role were considered "maybe a bit much" and are documented as a Roadmap idea below, not built.
**Security notes:**
- The edit server is configured to bind to `127.0.0.1`. This limits direct access to the local host; it does not replace host security controls.
- The password is stored as a PBKDF2-HMAC-SHA256 hash (`wiki_auth.json`, gitignored), never in plaintext. This hash defends against a casual read of the file revealing a reused password — it does **not** defend against local filesystem access; anyone who can already read/write files on the machine can replace `wiki_auth.json` outright. Forgotten password? Delete `wiki_auth.json` to return to the default (no password, full rights for everyone).
- Every mutating request must carry `Content-Type: application/json` (rejects classic `