OKF Manager

OKF Manager provides portable Open Knowledge Format (OKF) catalog management for Agent Zero projects and the global user workspace.

Version 0.4.0 adds deterministic generated glossaries and the current live D3 catalog view, while preserving Agent Zero's native okf_mgr profile, profile-local Tool wrappers, plugin-local worker environment, project/global path behavior, and Browser side-panel stability constraints.

<img width="2258" height="1047" alt="OKF Graph View" src="https://github.com/user-attachments/assets/2f8f2d39-8545-4638-b8c7-0db205fe44cb" />

Included capabilities

• okf-project-manager orchestration skill for project-local or global catalogs.
• okf_mgr specialist profile with native Agent Zero Tool wrappers and matching tool prompts.
• Deterministic concept read/write/list, bulk writing, raw-evidence cleanup, linting, strict validation, index generation, generated glossary support, live visualization, and graph verification.
• A plugin-local .venv, bootstrapped from requirements-worker.txt; framework Tool imports remain in /opt/venv-a0.
• Bounded web ingestion with host/path/depth/page guards, redirect validation, response-size limits, and persistent crawl state.

Install

Install the plugin at:

/a0/usr/plugins/okf_manager/

Enable it in Agent Zero's Plugins UI if needed. For a quick trial, create a blank Agent Zero project and ask:

Ingest <your_collection_of_files> and display its graph

Creating a new bundle always requires explicit confirmation. Existing catalogs can be maintained without creation confirmation.

Catalog placement

Resolution order:

1. An explicit catalog path from the user or project instructions.
2. The single existing project-local okf/*/ catalog, when an Agent Zero project is active.
3. The single existing global /a0/usr/okf/*/ catalog when no project is active.
4. Otherwise, propose <project-root>/okf/catalog/ or /a0/usr/okf/catalog/ and ask for confirmation before creating it.

Concepts live under <okf-root>/catalog/. Retained source evidence lives in sibling <okf-root>/raw/<meaningful-name>/; internal files, repositories, caches, virtual environments, dependencies, logs, and generated artifacts are excluded.

Catalog contract

Concept Markdown uses YAML frontmatter with:

• type
• title
• description
• timestamp as a strict ISO 8601 value
• optional resource, tags, and extension keys

Concept IDs use safe relative path segments. index, log, and glossary are reserved at every hierarchy level.

Generated documents:

• index.md: directory indexes.
• log.md: chronological update history.
• glossary.md: deterministic terms occurring in at least two concepts by default. Never edit it manually.
• viz.html: generated interactive catalog view.

Generated Markdown documents are excluded from concept counts and concept-frontmatter checks, but their local links are linted. Catalog documents may link to sibling ../raw/... evidence; those links are checked for existence.

Deterministic runner

Use scripts/okf_run.py; do not run workflows with bare python. The runner bootstraps and reuses the plugin-local worker environment.

./scripts/okf_run.py validate --catalog /path/to/project/okf/catalog
./scripts/okf_run.py glossary --catalog /path/to/project/okf/catalog
./scripts/okf_run.py index --catalog /path/to/project/okf/catalog
./scripts/okf_run.py visualize --catalog /path/to/project/okf/catalog
./scripts/okf_run.py verify-graph --catalog /path/to/project/okf/catalog

The recommended post-edit pipeline is:

./scripts/okf_run.py pipeline --catalog /path/to/project/okf/catalog

Pipeline order is fixed: clean raw evidence, generate glossary.md, lint, validate, regenerate indexes, generate viz.html, and verify the embedded graph and glossary payload.

Named and positional catalog arguments remain supported for compatibility.

Live visualization

The plugin owns one shared template at scripts/assets/viz-template.html; both the standalone visualizer and native okf_mgr Tool use it. The generated live D3 view includes:

• concept-tree navigation and search;
• per-type and per-concept visibility controls;
• embedded glossary data with glossary-to-concept navigation;
• collapsible/resizable navigation and detail sections;
• concept back/forward history, outgoing links, backlinks, and Markdown body preview;
• script-safe JSON embedding, including safe </script escaping.

D3 loads from https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js. Visualization requests load the absolute file://.../viz.html in the Agent Zero Browser. If the Browser side panel is not visible, open it manually. The template intentionally avoids hover/mousemove tooltips and layout-reactive resize observers that destabilize Agent Zero's constrained side panel.

Web-ingestion and network disclosure

The native okf_fetch_url Tool and standalone fetch-url runner command make user-directed HTTP(S) requests. They enforce approved hosts and paths, crawl page/depth budgets, visited state, post-redirect validation, a 2 MiB response limit, and a 40 KiB Markdown limit. HTML is converted with markdownify.

The native Tool keeps crawl state in the active okf_mgr agent. The standalone command can persist state to JSON in a user-selected location:

./scripts/okf_run.py fetch-url https://docs.example.test/start \
  --state /tmp/okf-crawl.json \
  --allowed-host docs.example.test \
  --allowed-path-prefix /guide/

This feature is not intended for indiscriminate open-web crawling.

Repository layout

okf_manager/
├── plugin.yaml
├── default_config.yaml
├── requirements-worker.txt
├── skills/okf-project-manager/SKILL.md
├── agents/okf_mgr/
│   ├── agent.yaml
│   ├── prompts/
│   ├── skills/
│   └── tools/
├── scripts/
│   ├── assets/viz-template.html
│   ├── okf_generate_glossary.py
│   ├── okf_run.py
│   ├── okf_validate_bundle.py
│   ├── okf_visualize_bundle.py
│   └── okf_verify_graph.py
└── tests/

Cross-port provenance and compatibility

The substantive glossary, workflow, validation, and visualization behavior was compared against the Codex port at source commit 1818008282454a00519d2902c7731eed258c19ad and adapted rather than copied wholesale.

Deliberately retained Agent Zero behavior includes native profile Tool wrappers, agent-scoped crawl state, the plugin-local worker .venv, Agent Zero Browser instructions, project/global catalog resolution, explicit creation confirmation, and stable side-panel constraints. Codex cache/runtime wrappers, agents/openai.yaml, duplicate thumbnails, and narrower BigQuery replacements are not included.

Community Plugin Index

The runtime manifest is plugin.yaml. The separate Plugin Index entry is docs/community/index.yaml; do not confuse these schemas. The community thumbnail is docs/community/thumbnail.png.

License

MIT. See LICENSE.