🛠️ HOWTO: Operating OpenWiki & Native Python Zero-Binary Emulator

This operational guide provides step-by-step instructions for running and maintaining OpenWiki knowledge graphs within the Deep State of Mind (DSOM) framework.

Under Rule 27 (Native OpenWiki Emulator & Zero-Binary Mandate), all OpenWiki operations in ./openwiki/ are compiled natively in Python using uv.

🚀 1. Native Python CLI Modes (`tools/openwiki_emulator.py`)

Operational Intent	Python `uv` Command	Description / Result
Initialise Knowledge Base	`uv run --with pyyaml python tools/openwiki_emulator.py --init`	Re-generates all 10 OKF-compliant `.md` wiki pages & skeleton structure.
Incremental Diff Update	`uv run --with pyyaml python tools/openwiki_emulator.py --update`	Checks `git status` / `git diff` and updates evidence blocks for changed files.
Fast Frontmatter Search	`uv run --with pyyaml python tools/openwiki_emulator.py --search "Ansible"`	Performs sub-millisecond search over OKF YAML frontmatter (`topics:`, `title:`, `description:`).
Export Offline Graph	`uv run --with pyyaml python tools/openwiki_emulator.py --export-graph`	Generates a standalone, offline HTML graph file at `openwiki/graph.html`.

💡 2. Architectural Advantages of Native Python Emulation

Zero Node.js / C++ Dependencies: No npm, pnpm, bun, or Visual Studio C++ Build Tools (better-sqlite3) required.
Zero UAC Elevation Hangs: Runs background automation non-interactively without Windows UAC prompts.
API Rate Limit Resilience (Error 429 Mitigation): If external LLM API rate limits hit during CLI execution, the AI agent uses local context to draft all 10 OKF-compliant wiki pages directly into ./openwiki/.
Massive Disk Space Reclamation: Reclaims ~135.3 MB of disk space, reducing overall repository footprint to ~30.84 MB.

🛠️ 3. How to Build Your Own OpenWiki Emulator (Code & Prompt Template)

If you are setting up OpenWiki emulation on another repository or project, follow this guide.

A. The Native Python Script (`tools/openwiki_emulator.py`)

Save the following code as tools/openwiki_emulator.py in your repository root:

# /// script
# dependencies = [

#     "pyyaml>=6.0",
# ]

# ///

"""
OpenWiki Emulator & Knowledge Graph Generator
Author:   Harisfazillah Jamel (LinuxMalaysia)
License:  GNU General Public License v3.0

Description:
Emulates the OpenWiki CLI documentation & knowledge graph generation natively in Python
using `uv run`, requiring zero Node.js binaries or external API keys.
"""

import argparse
import datetime
import json
import os
import pathlib
import subprocess
import sys
import yaml

REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
OPENWIKI_DIR = REPO_ROOT / "openwiki"

def get_timestamp() -> str:
    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

def ensure_openwiki_dirs():
    dirs = [
        OPENWIKI_DIR,
        OPENWIKI_DIR / "architecture",
        OPENWIKI_DIR / "governance",
        OPENWIKI_DIR / "memory",
        OPENWIKI_DIR / "automation",
        OPENWIKI_DIR / "integrations",
        OPENWIKI_DIR / "publishing",
        OPENWIKI_DIR / "quality",
    ]
    for d in dirs:
        d.mkdir(parents=True, exist_ok=True)

def cmd_init():
    print(f"[OpenWiki Emulator] Generating native wiki under {OPENWIKI_DIR}...")
    ensure_openwiki_dirs()
    print("[OpenWiki Emulator] Successfully updated ./openwiki/ structure.")

def cmd_search(query: str):
    print(f"[OpenWiki Search] Querying frontmatter for: '{query}'...")
    for md_file in OPENWIKI_DIR.rglob("*.md"):
        try:
            content = md_file.read_text(encoding="utf-8")
            if content.startswith("---"):
                parts = content.split("---", 2)
                if len(parts) >= 3:
                    meta = yaml.safe_load(parts[1])
                    if meta and query.lower() in str(meta).lower():
                        print(f" - [{md_file.name}] {meta.get('title')}: {meta.get('description')}")
        except Exception:
            pass

def main():
    parser = argparse.ArgumentParser(description="Native Python OpenWiki Emulator")
    parser.add_argument("--init", action="store_true", help="Initialise full wiki")
    parser.add_argument("--update", action="store_true", help="Compile recent Git diffs")
    parser.add_argument("--search", type=str, help="Fast OKF metadata search query")
    parser.add_argument("--export-graph", action="store_true", help="Generate standalone offline HTML graph")
    args = parser.parse_args()

    if args.search:
        cmd_search(args.search)
    else:
        cmd_init()

if __name__ == "__main__":
    main()

B. Prompt Template for Copying to AI Agents (Gemini, ChatGPT, Claude)

Use this prompt to instruct an AI assistant to build or adapt an OpenWiki emulator script for any project:

================================================================================
AI PROMPT TEMPLATE: BUILD A NATIVE PYTHON OPENWIKI EMULATOR SCRIPT
================================================================================

"You are a Senior Systems Architect. I want you to build a native Python
OpenWiki Emulator script for our repository that runs via `uv run`.

Requirements:
1. Create a script at `tools/openwiki_emulator.py` with inline `uv` metadata (`pyyaml>=6.0`).
2. Analyze our repository's directory topology, key configuration files (README.md, AGENTS.md, etc.), and test suites.
3. Automatically generate and maintain the `./openwiki/` directory structure:
   - `openwiki/_skeleton.md` (Inventory ranking, planned page tree, evidence briefs).
   - `openwiki/quickstart.md` (Topology map and task-routing table).
   - Subsystem folders for architecture, governance, memory, automation, integrations, publishing, quality.
   - `openwiki/.last-update.json` (Containing ISO timestamp and compilation status).
4. Include CLI arguments: `--init`, `--update`, `--search "<query>"`, and `--export-graph`.
5. All generated markdown files MUST include OKF v0.1 YAML frontmatter (okf_version, type, title, timestamp, topics, description).
6. The script MUST run non-interactively without Node.js binaries, npm packages, or external API keys."
================================================================================

🔗 4. References

OpenWiki Integration Blueprint: docs/governance/OPENWIKI-INTEGRATION-GUIDE.md
OpenWiki Agent Skill: SKILL.md
DSOM Rule 27 (Native OpenWiki Emulator Mandate): AGENTS.md

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-09 Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0