Skip to content

ADOPTION.md

Latest commit

 

History

History
98 lines (73 loc) · 3.74 KB

ADOPTION.md

File metadata and controls

98 lines (73 loc) · 3.74 KB
Raw

Adoption guide

What this package provides

This ZIP is a complete working reference repository, not only a library. It combines:

  • the canonical Artagon Zanzibar research vault;
  • immutable original source files and manifests;
  • a Python 3.10+ metadata compiler;
  • a schema registry and temporal/provenance profile;
  • a tamper-evident semantic event ledger;
  • deterministic RDF, agent-memory, OKF, schema.org, Data Commons, RO-Crate, Quartz, and GitBook outputs;
  • twenty-one Agent Skills;
  • ten specialized maintenance agents;
  • tests, validation, adversarial review, release manifests, and recovery guidance.

Minimal evaluation

python -m venv .venv
. .venv/bin/activate
pip install -e './plugins/artagon-vault-curator[all]'

CLI=artagon-vault
$CLI --vault . doctor
$CLI --vault . status
$CLI --vault . schema-status
$CLI --vault . events-verify
$CLI --vault . compiler-plan --target all
$CLI --vault . compiler-audit --strict
python -m pytest plugins/artagon-vault-curator/tests -q

Authoring model

Edit only authoritative inputs:

canonical Markdown entity notes
90-Meta/Schema/
90-Meta/Events/knowledge-events.jsonl through the CLI
immutable source manifests through controlled intake
reviewed proposal records

Do not edit generated compiler overlays, graph exports, agent memory, OKF, RO-Crate, Quartz, or GitBook files.

Semantic change protocol

  1. Retrieve existing entities and evidence.
  2. Dry-run validation and compiler plan.
  3. Edit canonical notes or schema.
  4. Reconcile semantic events with a stable actor ID.
  5. Build affected targets.
  6. Run strict compiler audit and repository validation.
  7. Publish only after all gates pass.

Bringing another vault into the model

  1. Copy plugins/artagon-vault-curator/ and merge the local marketplace entry.
  2. Adapt .artagon-vault.json canonical paths.
  3. Run schema-init --apply and review the generated registry.
  4. Resolve duplicate IDs and URI mismatches before event bootstrap.
  5. Run events-bootstrap --actor ART-AGENT-MIGRATION --apply.
  6. Build targets and inspect compiler issues and conflict candidates.
  7. Keep schema 1.x fields readable during a reviewed migration period.

Bootstrap establishes when the new compiler first recorded the current state. It does not reconstruct an unknown historical transaction timeline.

Deployment boundaries

  • Obsidian is the canonical editing environment.
  • Quartz is the discovery-oriented human projection.
  • GitBook is the guided handbook projection.
  • OKF is a portable human/agent interchange projection.
  • RDF and the property graph are formal/operational projections.
  • Agent-memory JSONL is the retrieval projection.
  • RO-Crate packages research and release context.

Native Quartz rendering and hosted GitBook import should be tested in their actual deployment environments. Public publication requires explicit publish: true, licensing/privacy review, and access-control review.

Third-party skills

See plugins/artagon-vault-curator/references/THIRD_PARTY_SKILLS.md. Links are pinned to reviewed commits where possible, but no external skill is implicitly trusted. Audit the complete repository before installation.

Local agent and store integration

Read INTEGRATIONS.md. The adoption package includes a read-only MCP server, client templates, portable Obsidian configuration, a prebuilt SQLite FTS5 store, and explicit dry-run-first loaders for Neo4j, PostgreSQL/pgvector, Qdrant, and Fuseki.

pip install -e './plugins/artagon-vault-curator[mcp,stores,compiler]'
artagon-vault --vault . mcp-doctor
artagon-vault --vault . store-status
artagon-vault --vault . integration-audit --strict

External services are optional caches. They do not become authoritative and are never contacted during deterministic compiler builds.