> ## Documentation Index
> Fetch the complete documentation index at: https://harisfazillah.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Step-by-step operational guide for maintaining OpenWiki knowledge graphs natively via Python (uv) without Node.js binaries or external API rate limits.

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

1. **Zero Node.js / C++ Dependencies:** No `npm`, `pnpm`, `bun`, or Visual Studio C++ Build Tools (`better-sqlite3`) required.
2. **Zero UAC Elevation Hangs:** Runs background automation non-interactively without Windows UAC prompts.
3. **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/`.
4. **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:

```python theme={null}

# /// 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:

```text theme={null}
================================================================================
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`](file:///docs/governance/OPENWIKI-INTEGRATION-GUIDE)
* **OpenWiki Agent Skill:** [`SKILL.md`](file:///.agents/skills/openwiki-compiler/SKILL.md)
* **DSOM Rule 27 (Native OpenWiki Emulator Mandate):** [`AGENTS.md`](file:///AGENTS)

***

*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*


## Related topics

- [🌐 OpenWiki Integration Blueprint & Native Python Emulator Architecture](/governance/openwiki-integration-guide.md)
- [Google Jules & Google Antigravity Collaborative Sync](/skills/jules-antigravity-sync.md)
- [OpenWiki Knowledge Graph Compiler Skill](/skills/openwiki-compiler.md)
- [Explanation: OpenWiki & FastMCP Architecture](/explanation/openwiki-mcp-architecture.md)
- [Reference: openwiki_emulator.py](/reference/openwiki_emulator.md)