From 3669f63b117bc4838a6e6690681d68241aaa94e8 Mon Sep 17 00:00:00 2001 From: Ethan Davidson <31261035+EthanThatOneKid@users.noreply.github.com> Date: Mon, 13 Jul 2026 17:47:57 -0700 Subject: [PATCH] feat: rename Wiki_CLI and Wiki_Subcommand_* docs pages to wiki and wiki_* Rename: Wiki_CLI.md -> wiki.md (H1: # Wiki CLI -> # \wiki\) Wiki_Subcommand_{build,check,export,fmt,graph,init,install,link,lint,mcp,query,remove,render,serve,update,upgrade}.md -> wiki_{}.md Update all ~210 internal cross-reference links across 35+ docs wiki files. Update external references in scripts/, tests/, AGENTS.md, README.md, CHANGELOG.md, CONTEXT.md. Add redirect stubs at old paths (using wazoo:layout: layouts/redirect.html) so /Wiki_CLI/ -> /wiki/, /Wiki_Subcommand_*/ -> /wiki_*/. Add link.renames map in docs/wiki.yml for wiki link --fix-broken. --- AGENTS.md | 6 +- CHANGELOG.md | 2 +- CONTEXT.md | 2 +- README.md | 8 +- docs/build.py | 9 + docs/layouts/redirect.html | 12 + docs/wiki.yml | 21 +- docs/wiki/Agent_Memory_Filesystems.md | 10 +- docs/wiki/CSV.md | 4 +- docs/wiki/Content_Negotiation.md | 10 +- docs/wiki/Dataview_Integration.md | 4 +- docs/wiki/Declarative_Knowledge.md | 6 +- docs/wiki/Deploying_to_GitHub_Pages.md | 2 +- docs/wiki/Design_Philosophies.md | 12 +- docs/wiki/Farzapedia.md | 10 +- docs/wiki/Getting_Started.md | 20 +- docs/wiki/Graph_Cache.md | 14 +- docs/wiki/JSON_LD.md | 6 +- docs/wiki/Jeff_Kazzee.md | 2 +- docs/wiki/LLM_Wiki.md | 6 +- docs/wiki/Learning_Systems.md | 10 +- docs/wiki/Letta_MemFS.md | 4 +- docs/wiki/Linked_Markdown.md | 2 +- docs/wiki/Microdata.md | 2 +- docs/wiki/N_Quads.md | 4 +- docs/wiki/N_Triples.md | 4 +- docs/wiki/Notation3.md | 2 +- docs/wiki/OWL.md | 6 +- docs/wiki/Obsidian.md | 2 +- docs/wiki/Obsidian_Integration.md | 10 +- docs/wiki/Personal_Knowledge.md | 2 +- docs/wiki/Procedural_Knowledge.md | 10 +- docs/wiki/Python_API_Reference.md | 2 +- docs/wiki/RDF.md | 2 +- docs/wiki/RDF_XML.md | 4 +- docs/wiki/Recursive_Semantic_Datasets.md | 4 +- docs/wiki/SHACL.md | 6 +- docs/wiki/SPARQL.md | 12 +- docs/wiki/Semantic_Web.md | 2 +- docs/wiki/Style_Guide.md | 16 +- docs/wiki/Supermemory_SMFS.md | 4 +- docs/wiki/TriG.md | 4 +- docs/wiki/Turtle.md | 2 +- docs/wiki/Vivary.md | 6 +- docs/wiki/WikiThon.md | 4 +- docs/wiki/Wiki_CLI.md | 322 +---------------------- docs/wiki/Wiki_Configuration.md | 24 +- docs/wiki/Wiki_Page_Layouts.md | 4 +- docs/wiki/Wiki_Programmatic_API.md | 4 +- docs/wiki/Wiki_Skills.md | 4 +- docs/wiki/Wiki_Subcommand_build.md | 69 +---- docs/wiki/Wiki_Subcommand_check.md | 84 +----- docs/wiki/Wiki_Subcommand_export.md | 51 +--- docs/wiki/Wiki_Subcommand_fmt.md | 87 +----- docs/wiki/Wiki_Subcommand_graph.md | 58 +--- docs/wiki/Wiki_Subcommand_init.md | 84 +----- docs/wiki/Wiki_Subcommand_install.md | 46 +--- docs/wiki/Wiki_Subcommand_link.md | 66 +---- docs/wiki/Wiki_Subcommand_lint.md | 73 +---- docs/wiki/Wiki_Subcommand_mcp.md | 146 +--------- docs/wiki/Wiki_Subcommand_query.md | 90 +------ docs/wiki/Wiki_Subcommand_remove.md | 29 +- docs/wiki/Wiki_Subcommand_render.md | 165 +----------- docs/wiki/Wiki_Subcommand_serve.md | 106 +------- docs/wiki/Wiki_Subcommand_update.md | 40 +-- docs/wiki/Wiki_Subcommand_upgrade.md | 50 +--- docs/wiki/wiki.md | 319 ++++++++++++++++++++++ docs/wiki/wiki_build.md | 68 +++++ docs/wiki/wiki_check.md | 83 ++++++ docs/wiki/wiki_export.md | 50 ++++ docs/wiki/wiki_fmt.md | 86 ++++++ docs/wiki/wiki_graph.md | 57 ++++ docs/wiki/wiki_init.md | 83 ++++++ docs/wiki/wiki_install.md | 45 ++++ docs/wiki/wiki_link.md | 65 +++++ docs/wiki/wiki_lint.md | 72 +++++ docs/wiki/wiki_mcp.md | 145 ++++++++++ docs/wiki/wiki_query.md | 89 +++++++ docs/wiki/wiki_remove.md | 28 ++ docs/wiki/wiki_render.md | 164 ++++++++++++ docs/wiki/wiki_serve.md | 105 ++++++++ docs/wiki/wiki_update.md | 39 +++ docs/wiki/wiki_upgrade.md | 49 ++++ scripts/release.py | 6 +- scripts/set_version.py | 12 +- tests/test_audit.py | 4 +- tests/test_cli.py | 4 +- tests/test_format.py | 2 +- tests/test_link_suggest.py | 18 +- tests/test_site.py | 10 +- tests/test_version.py | 2 +- 91 files changed, 1828 insertions(+), 1671 deletions(-) create mode 100644 docs/layouts/redirect.html create mode 100644 docs/wiki/wiki.md create mode 100644 docs/wiki/wiki_build.md create mode 100644 docs/wiki/wiki_check.md create mode 100644 docs/wiki/wiki_export.md create mode 100644 docs/wiki/wiki_fmt.md create mode 100644 docs/wiki/wiki_graph.md create mode 100644 docs/wiki/wiki_init.md create mode 100644 docs/wiki/wiki_install.md create mode 100644 docs/wiki/wiki_link.md create mode 100644 docs/wiki/wiki_lint.md create mode 100644 docs/wiki/wiki_mcp.md create mode 100644 docs/wiki/wiki_query.md create mode 100644 docs/wiki/wiki_remove.md create mode 100644 docs/wiki/wiki_render.md create mode 100644 docs/wiki/wiki_serve.md create mode 100644 docs/wiki/wiki_update.md create mode 100644 docs/wiki/wiki_upgrade.md diff --git a/AGENTS.md b/AGENTS.md index 30ed971..4bb4883 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Use Markdown links for all internal and external URLs. ### Formatting (`wiki fmt`) - **Rule:** After editing any wiki page under `docs/wiki/` (including reference docs such as [Wiki Configuration](docs/wiki/Wiki_Configuration.md)), run `wiki fmt` on the changed files before commit. Do not hand-align markdown tables or list spacing — mdformat owns mechanical layout; CI fails on drift. -- **Enforcer:** `wiki fmt --check` in CI (same order as [Wiki Subcommand lint](docs/wiki/Wiki_Subcommand_lint.md): fmt → lint → check). +- **Enforcer:** `wiki fmt --check` in CI (same order as [wiki lint](docs/wiki/wiki_lint.md): fmt → lint → check). ## Developer notes @@ -104,11 +104,11 @@ Use the release helper for the normal path: uv run python scripts/release.py patch --message "Fix graph URI resolution" --issue 215 --full --push --watch ``` -The helper bumps all enforced version surfaces (`pyproject.toml`, `package.json`, `package-lock.json`, `uv.lock`, `src/wiki/__init__.py`, and `docs/wiki/Wiki_CLI.md`), updates `CHANGELOG.md`, regenerates inline SPARQL result blocks, formats docs, runs validation, commits, tags, pushes, and optionally watches GitHub Actions. +The helper bumps all enforced version surfaces (`pyproject.toml`, `package.json`, `package-lock.json`, `uv.lock`, `src/wiki/__init__.py`, and `docs/wiki/wiki.md`), updates `CHANGELOG.md`, regenerates inline SPARQL result blocks, formats docs, runs validation, commits, tags, pushes, and optionally watches GitHub Actions. Manual fallback: -1. **Bump version** in all enforced places: `pyproject.toml`, `package.json`, `package-lock.json`, `uv.lock`, `src/wiki/__init__.py`, and `docs/wiki/Wiki_CLI.md` (they must match — CI verifies this). +1. **Bump version** in all enforced places: `pyproject.toml`, `package.json`, `package-lock.json`, `uv.lock`, `src/wiki/__init__.py`, and `docs/wiki/wiki.md` (they must match — CI verifies this). 2. **Update `CHANGELOG.md`** with the new version's entries. 3. **Regenerate docs outputs** with `wiki -c docs/wiki.yml render`, then run `wiki -c docs/wiki.yml fmt` on touched docs. 4. **Commit and push** the version bump. Tag it with `v` (e.g., `v0.1.18`). diff --git a/CHANGELOG.md b/CHANGELOG.md index c97caca..e34f10f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -103,7 +103,7 @@ link: ### Changed -- Consolidate [Wiki CLI templates](docs/wiki/Wiki_CLI.md#ecosystem-templates) registry in Wiki_CLI: single shipped/planned table, SPARQL single-repo (`wiki-yasgui-template` absorbs Virtuoso scope), `wiki-{stack}-template` integration slugs, planned `wiki-astro-template` ([#96](https://github.com/wazootech/wiki/issues/96)). Slim README and downstream wiki pages to point at the canonical section; retire stale slugs (`sparql-service-template`, bare `nextjs-template`, `obsidian-quartz-template`, etc.). +- Consolidate [Wiki CLI templates](docs/wiki/wiki.md#ecosystem-templates) registry in Wiki_CLI: single shipped/planned table, SPARQL single-repo (`wiki-yasgui-template` absorbs Virtuoso scope), `wiki-{stack}-template` integration slugs, planned `wiki-astro-template` ([#96](https://github.com/wazootech/wiki/issues/96)). Slim README and downstream wiki pages to point at the canonical section; retire stale slugs (`sparql-service-template`, bare `nextjs-template`, `obsidian-quartz-template`, etc.). - Remove `site.manifest` and `manifest.webmanifest`. Branding (site name, theme color, favicon, sidebar logo) lives in `site.layout` only; `wiki.yaml` `site:` keeps `layout`, `base_url`, and `url_style`. A brief 0.1.14 release added `--site-name` and `--site-theme-color` for logo SVG only; those init flags were removed before the next release — see Unreleased migration for the tweak-comment workflow. - `wiki init` omits `lint:` keys that default to `off` (`headings`, `heading_levels`, `duplicate_headings`, `thematic_breaks`). - Docs and agent skills use title-case H1 headings and sentence-case H2+ without numbered headings. diff --git a/CONTEXT.md b/CONTEXT.md index d8b2d5a..665b437 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,6 +1,6 @@ # Wiki CLI (`wazootech-wiki`) -Semantic knowledge **toolchain** for Markdown wikis: compile frontmatter and body into RDF, validate with SHACL and JSON Schema, infer with OWL-RL, query with SPARQL, and publish static HTML or serializations. Wiki CLI is the compiler and query engine — not the primary editor or note app. See [docs/wiki/Wiki_CLI.md](docs/wiki/Wiki_CLI.md) for scope, boundaries, and command reference. +Semantic knowledge **toolchain** for Markdown wikis: compile frontmatter and body into RDF, validate with SHACL and JSON Schema, infer with OWL-RL, query with SPARQL, and publish static HTML or serializations. Wiki CLI is the compiler and query engine — not the primary editor or note app. See [docs/wiki/wiki.md](docs/wiki/wiki.md) for scope, boundaries, and command reference. ## Architecture decision: Python core diff --git a/README.md b/README.md index fdf36da..d22fdba 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Repository: [github.com/wazootech/wiki](https://github.com/wazootech/wiki). CLI command: `wiki`. Install via [pip](https://pypi.org/project/wazootech-wiki/) or [npm](https://www.npmjs.com/package/wazootech-wiki). -Starter template: [wiki-template](https://github.com/wazootech/wiki-template) (generic wiki project). See [Wiki CLI templates](docs/wiki/Wiki_CLI.md#ecosystem-templates). +Starter template: [wiki-template](https://github.com/wazootech/wiki-template) (generic wiki project). See [Wiki CLI templates](docs/wiki/wiki.md#ecosystem-templates). ## Use cases and integrations @@ -28,7 +28,7 @@ While inspired by personal digital gardens like **Farzapedia** (a subjective, fi - **Farzapedia** is a specific *content wiki* containing diary entries, notes, and messages. - **Wiki CLI** is a *utility* for *any* wiki. It validates structure, runs queries, and builds static websites from a folder of Markdown files. -Adoption path: [Wiki CLI](docs/wiki/Wiki_CLI.md) in the docs wiki. +Adoption path: [Wiki CLI](docs/wiki/wiki.md) in the docs wiki. ## Key features @@ -59,7 +59,7 @@ Use these GitHub template repos to kickstart a new wiki or preview one of Wiki C Also see [wiki-wikipedia-template](https://github.com/wazootech/wiki-wikipedia-template) — a standalone Jinja2 Wikipedia-themed layout using the Wiki Python API (not a GitHub template, but a reference implementation). -All templates are in the [wazootech](https://github.com/wazootech) organization. Full details: [Wiki CLI templates](docs/wiki/Wiki_CLI.md#ecosystem-templates). +All templates are in the [wazootech](https://github.com/wazootech) organization. Full details: [Wiki CLI templates](docs/wiki/wiki.md#ecosystem-templates). ## Installation @@ -287,7 +287,7 @@ link: style: standard ``` -**Wikipedia-style** names (for example `Gregory_Davidson.md`, `Wiki_CLI.md`) are the recommended default. Lowercase kebab-case is optional — only use it if you configure a matching pattern (for example `[a-z0-9-]+\\.md`). Build-safety rules, such as rejecting spaces and unsafe URL characters in page paths, are always enforced separately in `wiki check`. +**Wikipedia-style** names (for example `Gregory_Davidson.md`, `LLM_Wiki.md`) are the recommended default. Lowercase kebab-case is optional — only use it if you configure a matching pattern (for example `[a-z0-9-]+\\.md`). Build-safety rules, such as rejecting spaces and unsafe URL characters in page paths, are always enforced separately in `wiki check`. ### `link` Suggest missing wikilinks for plain-text page mentions, or repair unambiguous broken internal links. Report-only by default. diff --git a/docs/build.py b/docs/build.py index 982e61c..fbfb328 100644 --- a/docs/build.py +++ b/docs/build.py @@ -342,6 +342,8 @@ def _build_index_page(site, base_url, url_style, pages_json, layout_text): links_html = "" seen_files: set[str] = set() for page in site.pages: + if page.frontmatter.get("redirect_to"): + continue if page.file_slug not in seen_files: seen_files.add(page.file_slug) cats = _get_page_categories(page) @@ -453,6 +455,13 @@ def build(output_dir: Path) -> None: edit_link_html=edit_link_html, ) + redirect_to = page.frontmatter.get("redirect_to") + if redirect_to: + tokens["%wiki.redirect_url%"] = page_href(base_url, redirect_to, url_style) + layout_text = (script_dir / "layouts" / "redirect.html").read_text(encoding="utf-8") + else: + tokens["%wiki.redirect_url%"] = "" + html = substitute(layout_text, tokens) out = page_output_path(wiki_output, page.full_slug, url_style) diff --git a/docs/layouts/redirect.html b/docs/layouts/redirect.html new file mode 100644 index 0000000..b33c49a --- /dev/null +++ b/docs/layouts/redirect.html @@ -0,0 +1,12 @@ + + + + + + +Redirecting... + + +

Redirecting to %wiki.redirect_url%...

+ + diff --git a/docs/wiki.yml b/docs/wiki.yml index 5c18b52..439df2d 100644 --- a/docs/wiki.yml +++ b/docs/wiki.yml @@ -45,8 +45,24 @@ site: link: # standard page links or wikilinks (wiki link --apply). style: standard - # renames: - # Old_Page_Name: New_Page_Name + renames: + Wiki_CLI: wiki + Wiki_Subcommand_build: wiki_build + Wiki_Subcommand_check: wiki_check + Wiki_Subcommand_export: wiki_export + Wiki_Subcommand_fmt: wiki_fmt + Wiki_Subcommand_graph: wiki_graph + Wiki_Subcommand_init: wiki_init + Wiki_Subcommand_install: wiki_install + Wiki_Subcommand_link: wiki_link + Wiki_Subcommand_lint: wiki_lint + Wiki_Subcommand_mcp: wiki_mcp + Wiki_Subcommand_query: wiki_query + Wiki_Subcommand_remove: wiki_remove + Wiki_Subcommand_render: wiki_render + Wiki_Subcommand_serve: wiki_serve + Wiki_Subcommand_update: wiki_update + Wiki_Subcommand_upgrade: wiki_upgrade # Integrity severities (wiki check): SHACL, JSON Schema, routes, layout files. check: @@ -82,3 +98,4 @@ fmt: # Pointer mode (optional TOML file relative to this file): # fmt: .mdformat.toml + diff --git a/docs/wiki/Agent_Memory_Filesystems.md b/docs/wiki/Agent_Memory_Filesystems.md index b0835f4..5c2a489 100644 --- a/docs/wiki/Agent_Memory_Filesystems.md +++ b/docs/wiki/Agent_Memory_Filesystems.md @@ -6,17 +6,17 @@ description: Comparison of filesystem-metaphor approaches for long-term LLM agen # Agent Memory Filesystems -A growing class of tools gives LLM agents **persistent memory through a filesystem metaphor**: `ls`, `cat`, `grep`, and markdown-shaped trees instead of bespoke vector SDKs or unbounded chat context. Three prominent approaches—**[Wiki CLI](Wiki_CLI.md)**, **[Supermemory SMFS](Supermemory_SMFS.md)**, and **[Letta MemFS](Letta_MemFS.md)**—all support the [LLM Wiki](LLM_Wiki.md) / [Personal Knowledge](Personal_Knowledge.md) vision but optimize for different backends and workflows. +A growing class of tools gives LLM agents **persistent memory through a filesystem metaphor**: `ls`, `cat`, `grep`, and markdown-shaped trees instead of bespoke vector SDKs or unbounded chat context. Three prominent approaches—**[wiki](wiki.md)**, **[Supermemory SMFS](Supermemory_SMFS.md)**, and **[Letta MemFS](Letta_MemFS.md)**—all support the [LLM Wiki](LLM_Wiki.md) / [Personal Knowledge](Personal_Knowledge.md) vision but optimize for different backends and workflows. ## Shared idea Traditional chat UIs are largely stateless. These systems let an agent (and often a human) **read and write durable artifacts** as files, compounding knowledge across sessions. They pair well with coding agents ([Obsidian Integration](Obsidian_Integration.md) as viewer, terminal tools as compiler) but differ in where truth lives and how recall works. -## Comparison with [Wiki CLI](Wiki_CLI.md), [Letta MemFS](Letta_MemFS.md), and [Supermemory SMFS](Supermemory_SMFS.md) +## Comparison with [wiki](wiki.md), [Letta MemFS](Letta_MemFS.md), and [Supermemory SMFS](Supermemory_SMFS.md) ### Feature matrix -| | [Wiki CLI](Wiki_CLI.md) | [Supermemory SMFS](Supermemory_SMFS.md) | [Letta MemFS](Letta_MemFS.md) | +| | [wiki](wiki.md) | [Supermemory SMFS](Supermemory_SMFS.md) | [Letta MemFS](Letta_MemFS.md) | | ------------------------ | ------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------- | | **Metaphor** | Semantic markdown **wiki** / codebase | Cloud container as **mount** or virtual bash | **Git repo** of memory markdown | | **Authority** | Your wiki on disk | Supermemory API | Local Git (+ Letta Cloud for API agents) | @@ -29,7 +29,7 @@ Traditional chat UIs are largely stateless. These systems let an agent (and ofte ### When to use which -**[Wiki CLI](Wiki_CLI.md)** — You want a **local-first, explicit, interlinked wiki** that doubles as documentation: [Declarative Knowledge](Declarative_Knowledge.md) in frontmatter, [Procedural Knowledge](Procedural_Knowledge.md) in `wiki check` / `wiki render`, optional [Retrieval Augmented Generation](Retrieval_Augmented_Generation.md)-style synthesis via SPARQL instead of opaque embeddings. Fits [Farzapedia](Farzapedia.md)-style gardens with machine-checkable structure. +**[wiki](wiki.md)** — You want a **local-first, explicit, interlinked wiki** that doubles as documentation: [Declarative Knowledge](Declarative_Knowledge.md) in frontmatter, [Procedural Knowledge](Procedural_Knowledge.md) in `wiki check` / `wiki render`, optional [Retrieval Augmented Generation](Retrieval_Augmented_Generation.md)-style synthesis via SPARQL instead of opaque embeddings. Fits [Farzapedia](Farzapedia.md)-style gardens with machine-checkable structure. **[Supermemory SMFS](Supermemory_SMFS.md)** — You need **scale, semantic recall, and integrations** (documents, images, Slack, Notion, etc.) with minimal agent onboarding: mount `agent_memory/` or drop in `@supermemory/bash` for serverless. Accept cloud authority and background graph maintenance. @@ -37,7 +37,7 @@ Traditional chat UIs are largely stateless. These systems let an agent (and ofte ## Complementary use -These are not always mutually exclusive. A team might maintain a published **[Wiki CLI](Wiki_CLI.md)** wiki for product knowledge while a Letta agent keeps **private MemFS** notes, or mount **SMFS** for ingested corpora that feed summaries written into the wiki. The [Wiki CLI](Wiki_CLI.md)’s strength is **shared, validated, link-stable markdown**; SMFS and MemFS optimize **per-agent runtime memory**. +These are not always mutually exclusive. A team might maintain a published **[wiki](wiki.md)** wiki for product knowledge while a Letta agent keeps **private MemFS** notes, or mount **SMFS** for ingested corpora that feed summaries written into the wiki. The [wiki](wiki.md)’s strength is **shared, validated, link-stable markdown**; SMFS and MemFS optimize **per-agent runtime memory**. ## Related pages diff --git a/docs/wiki/CSV.md b/docs/wiki/CSV.md index 953a0ac..5ed96fd 100644 --- a/docs/wiki/CSV.md +++ b/docs/wiki/CSV.md @@ -13,8 +13,8 @@ While traditionally non-semantic, tabular results from [SPARQL](SPARQL.md) SELEC ## Related - [SPARQL](SPARQL.md) -- [Wiki Subcommand query](Wiki_Subcommand_query.md) — `-f csv` -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint) — `Accept: text/csv` +- [wiki query](wiki_query.md) — `-f csv` +- [wiki serve](wiki_serve.md#sparql-endpoint) — `Accept: text/csv` ## References diff --git a/docs/wiki/Content_Negotiation.md b/docs/wiki/Content_Negotiation.md index b09c759..de84a76 100644 --- a/docs/wiki/Content_Negotiation.md +++ b/docs/wiki/Content_Negotiation.md @@ -39,15 +39,15 @@ In a [Semantic Web](Semantic_Web.md) compliant system, URIs identifying real-wor ## In this wiki -The [Wiki CLI](Wiki_CLI.md) applies content negotiation in two places: +The [wiki](wiki.md) applies content negotiation in two places: -- **Page metadata view** on [Wiki Subcommand build](Wiki_Subcommand_build.md) and [Wiki Subcommand serve](Wiki_Subcommand_serve.md#metadata-view) — format chips for JSON-LD, Turtle, N3, RDF/XML, N-Triples, TriG, and N-Quads -- **SPARQL endpoint** on `wiki serve` when enabled — `Accept` selects SPARQL Results JSON, CSV, TSV, or RDF graph serializations ([Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint)) +- **Page metadata view** on [wiki build](wiki_build.md) and [wiki serve](wiki_serve.md#metadata-view) — format chips for JSON-LD, Turtle, N3, RDF/XML, N-Triples, TriG, and N-Quads +- **SPARQL endpoint** on `wiki serve` when enabled — `Accept` selects SPARQL Results JSON, CSV, TSV, or RDF graph serializations ([wiki serve](wiki_serve.md#sparql-endpoint)) ## Related -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md) -- [Wiki Subcommand build](Wiki_Subcommand_build.md) +- [wiki serve](wiki_serve.md) +- [wiki build](wiki_build.md) - [RDF](RDF.md) - [JSON LD](JSON_LD.md) - [Turtle](Turtle.md) diff --git a/docs/wiki/Dataview_Integration.md b/docs/wiki/Dataview_Integration.md index 9f895e9..fbd543f 100644 --- a/docs/wiki/Dataview_Integration.md +++ b/docs/wiki/Dataview_Integration.md @@ -6,7 +6,7 @@ description: Query and visualize your semantic markdown files in Obsidian using # Dataview Integration -The [Wiki CLI](Wiki_CLI.md) and Obsidian's community **Dataview** plugin can be used together on the same Markdown wiki. Because both tools operate on plain text Markdown files and standard YAML/JSON frontmatter, they interoperate naturally without needing any data migration or conversion. +The [wiki](wiki.md) and Obsidian's community **Dataview** plugin can be used together on the same Markdown wiki. Because both tools operate on plain text Markdown files and standard YAML/JSON frontmatter, they interoperate naturally without needing any data migration or conversion. ## How they complement each other @@ -85,6 +85,6 @@ dv.table( ## Related - [Obsidian Integration](Obsidian_Integration.md) — executing CLI commands from Obsidian -- [Wiki CLI](Wiki_CLI.md) — command reference home +- [wiki](wiki.md) — command reference home - [SPARQL](SPARQL.md) — semantic web query background ``` diff --git a/docs/wiki/Declarative_Knowledge.md b/docs/wiki/Declarative_Knowledge.md index c828a9e..c9e402b 100644 --- a/docs/wiki/Declarative_Knowledge.md +++ b/docs/wiki/Declarative_Knowledge.md @@ -6,7 +6,7 @@ description: Knowing what — facts, types, and relationships expressed as struc # Declarative Knowledge -**Declarative knowledge** is "knowing what": facts, definitions, taxonomies, and explicit relationships. In this wiki it is represented primarily as YAML frontmatter on markdown pages, compiled into an [RDF](RDF.md) graph via the [Wiki CLI](Wiki_CLI.md). +**Declarative knowledge** is "knowing what": facts, definitions, taxonomies, and explicit relationships. In this wiki it is represented primarily as YAML frontmatter on markdown pages, compiled into an [RDF](RDF.md) graph via the [wiki](wiki.md). Examples include `schema:Person` fields on biography pages, `schema:TechArticle` metadata on guides, and typed links between entities. [SHACL](SHACL.md) and JSON Schema (`wazoo:jsonSchema`) validate that declarative statements stay complete and consistent. @@ -16,8 +16,8 @@ Pair declarative pages with [Procedural Knowledge](Procedural_Knowledge.md)—wo - [Procedural Knowledge](Procedural_Knowledge.md) - [RDF](RDF.md) -- [Wiki CLI](Wiki_CLI.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) +- [wiki](wiki.md) +- [wiki export](wiki_export.md) - [Tech Article Shape](Tech_Article_Shape.md) - [Software Application Shape](Software_Application_Shape.md) - [SHACL](SHACL.md) diff --git a/docs/wiki/Deploying_to_GitHub_Pages.md b/docs/wiki/Deploying_to_GitHub_Pages.md index 7fb72d7..0f0b77a 100644 --- a/docs/wiki/Deploying_to_GitHub_Pages.md +++ b/docs/wiki/Deploying_to_GitHub_Pages.md @@ -33,7 +33,7 @@ For your own wiki, copy the workflow and change: - `--site-base-url` to match your Pages path (`/wiki`, `/my-wiki`, or `''` for root) - `path` in `upload-pages-artifact` to the directory that contains your built `index.html` -See [Wiki Subcommand build](Wiki_Subcommand_build.md) for `site.url_style`, `wiki.assets`, and collision checks. +See [wiki build](wiki_build.md) for `site.url_style`, `wiki.assets`, and collision checks. ## Avoid these mistakes diff --git a/docs/wiki/Design_Philosophies.md b/docs/wiki/Design_Philosophies.md index a496491..5e56322 100644 --- a/docs/wiki/Design_Philosophies.md +++ b/docs/wiki/Design_Philosophies.md @@ -8,7 +8,7 @@ description: Unix-style CLI design for the Wiki CLI tool. ## Silence is golden -[Wiki Subcommand check](Wiki_Subcommand_check.md), [Wiki Subcommand lint](Wiki_Subcommand_lint.md), [Wiki Subcommand render](Wiki_Subcommand_render.md), and similar commands exit **0 with no output** on success. Use `-v` / `--verbose` when you want summaries. In CI, combine `check --strict -v` and `lint --strict -v` so warnings fail loudly. +[wiki check](wiki_check.md), [wiki lint](wiki_lint.md), [wiki render](wiki_render.md), and similar commands exit **0 with no output** on success. Use `-v` / `--verbose` when you want summaries. In CI, combine `check --strict -v` and `lint --strict -v` so warnings fail loudly. ## Check, lint, fmt, and link @@ -37,7 +37,7 @@ To format page margins and headers before sending directly to a connected printe # Print a document cat wiki/Getting_Started.md | pr -h "Getting Started" | lp -# Print SPARQL query results ([Wiki Subcommand query](Wiki_Subcommand_query.md), [SPARQL](SPARQL.md)) +# Print SPARQL query results ([wiki query](wiki_query.md), [SPARQL](SPARQL.md)) wiki query "SELECT ?given ?family WHERE { ?s schema:givenName ?given ; schema:familyName ?family }" | pr -h "Wiki People" | lp ``` @@ -49,17 +49,17 @@ To stream content directly to your default Windows printer: # Print a document Get-Content wiki/Getting_Started.md | Out-Printer -# Print SPARQL query results ([Wiki Subcommand query](Wiki_Subcommand_query.md), [SPARQL](SPARQL.md)) +# Print SPARQL query results ([wiki query](wiki_query.md), [SPARQL](SPARQL.md)) wiki query "SELECT ?given ?family WHERE { ?s schema:givenName ?given ; schema:familyName ?family }" | Out-Printer ``` ## Flat command surface -Subcommands are top-level (`wiki check`, not `wiki wiki check`). Global options [Wiki CLI](Wiki_CLI.md#global-options) apply everywhere. +Subcommands are top-level (`wiki check`, not `wiki wiki check`). Global options [wiki](wiki.md#global-options) apply everywhere. ## Userland over platform lock-in -Printing, PDF, and heavy formatting stay in your shell (`pr`, `lp`, Pandoc, etc.). Daily notes, note templates, vault search, task/tag dashboards, plugin reloads, DevTools, screenshots, DOM/CSS inspection, and sync belong to Obsidian CLI or Obsidian plugins. History and collaboration belong to Git. The wiki tool focuses on graph construction, validation, and site generation. [Wiki CLI templates](Wiki_CLI.md#ecosystem-templates) and editor integrations stay at the edges; core scope is the semantic layer — see [Wiki CLI](Wiki_CLI.md#toolchain-vs-authoring-surface). +Printing, PDF, and heavy formatting stay in your shell (`pr`, `lp`, Pandoc, etc.). Daily notes, note templates, vault search, task/tag dashboards, plugin reloads, DevTools, screenshots, DOM/CSS inspection, and sync belong to Obsidian CLI or Obsidian plugins. History and collaboration belong to Git. The wiki tool focuses on graph construction, validation, and site generation. [Wiki CLI templates](wiki.md#ecosystem-templates) and editor integrations stay at the edges; core scope is the semantic layer — see [wiki](wiki.md#toolchain-vs-authoring-surface). ## Why RDF and SPARQL @@ -71,7 +71,7 @@ While Labeled Property Graphs (LPGs) and query languages like Cypher are popular ## Related -- [Wiki CLI](Wiki_CLI.md) +- [wiki](wiki.md) - [RDF](RDF.md) - [SPARQL](SPARQL.md) - [LLM Wiki](LLM_Wiki.md) diff --git a/docs/wiki/Farzapedia.md b/docs/wiki/Farzapedia.md index 4e3d00d..16b1567 100644 --- a/docs/wiki/Farzapedia.md +++ b/docs/wiki/Farzapedia.md @@ -2,7 +2,7 @@ type: TechArticle headline: Farzapedia description: An interlinked digital garden serving as an example for the LLM Wiki pattern. -about: wiki:Wiki_CLI +about: wiki:wiki --- # Farzapedia @@ -28,7 +28,7 @@ Farzapedia champions four crucial properties of modern knowledge engineering: ## Dynamic querying in this wiki -The [Wiki CLI](Wiki_CLI.md) is a fully realized software pipeline built to make the Farzapedia pattern deterministic. By treating Markdown frontmatter as a queryable RDF knowledge graph, you can run powerful [SPARQL](SPARQL.md) queries with [Wiki Subcommand query](Wiki_Subcommand_query.md) and refresh live indexes with [Wiki Subcommand render](Wiki_Subcommand_render.md)—fulfilling the dream of a queryable, self-updating mind map. +The [wiki](wiki.md) is a fully realized software pipeline built to make the Farzapedia pattern deterministic. By treating Markdown frontmatter as a queryable RDF knowledge graph, you can run powerful [SPARQL](SPARQL.md) queries with [wiki query](wiki_query.md) and refresh live indexes with [wiki render](wiki_render.md)—fulfilling the dream of a queryable, self-updating mind map. ## References @@ -37,8 +37,8 @@ The [Wiki CLI](Wiki_CLI.md) is a fully realized software pipeline built to make ## Related - [LLM Wiki](LLM_Wiki.md) -- [Wiki CLI](Wiki_CLI.md) +- [wiki](wiki.md) - [SPARQL](SPARQL.md) -- [Wiki Subcommand query](Wiki_Subcommand_query.md) -- [Wiki Subcommand render](Wiki_Subcommand_render.md) +- [wiki query](wiki_query.md) +- [wiki render](wiki_render.md) - [Getting Started](Getting_Started.md) diff --git a/docs/wiki/Getting_Started.md b/docs/wiki/Getting_Started.md index 710b43d..de5a783 100644 --- a/docs/wiki/Getting_Started.md +++ b/docs/wiki/Getting_Started.md @@ -55,13 +55,13 @@ wiki init --repo wazootech/wiki wiki init --git ``` -`wiki init` writes `wiki.yml`, `README.md`, and a starter `wiki/` folder (`Person_Shape.md`, `Ethan_Davidson.md`). Use `--repo owner/repo` to infer GitHub Pages URLs without a prompt, or pass `--graph-context-wiki` / `--site-base-url` explicitly. By default it does not create a Git repository; use `--git` if you want that explicitly. Init requires a clean directory (no existing `wiki.yml`, `README.md`, or non-empty `wiki/`). See [Wiki Subcommand init](Wiki_Subcommand_init.md) for all flags. +`wiki init` writes `wiki.yml`, `README.md`, and a starter `wiki/` folder (`Person_Shape.md`, `Ethan_Davidson.md`). Use `--repo owner/repo` to infer GitHub Pages URLs without a prompt, or pass `--graph-context-wiki` / `--site-base-url` explicitly. By default it does not create a Git repository; use `--git` if you want that explicitly. Init requires a clean directory (no existing `wiki.yml`, `README.md`, or non-empty `wiki/`). See [wiki init](wiki_init.md) for all flags. ### Branding -Styling and branding (such as site name, theme color, logo, and favicon) are not managed by the CLI out-of-the-box, which outputs plain, unstyled HTML. To add custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` in your `wiki.yml`. See [Wiki Configuration — Custom CSS](Wiki_Configuration.md#custom-css) and [Wiki Subcommand init](Wiki_Subcommand_init.md). +Styling and branding (such as site name, theme color, logo, and favicon) are not managed by the CLI out-of-the-box, which outputs plain, unstyled HTML. To add custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` in your `wiki.yml`. See [Wiki Configuration — Custom CSS](Wiki_Configuration.md#custom-css) and [wiki init](wiki_init.md). -Alternatively, start from a GitHub template: [wiki-template](https://github.com/wazootech/wiki-template) (generic wiki project) or the [LLM Wiki](LLM_Wiki.md) starter [llm-wiki-template](https://github.com/wazootech/llm-wiki-template). See [Wiki CLI templates](Wiki_CLI.md#ecosystem-templates). +Alternatively, start from a GitHub template: [wiki-template](https://github.com/wazootech/wiki-template) (generic wiki project) or the [LLM Wiki](LLM_Wiki.md) starter [llm-wiki-template](https://github.com/wazootech/llm-wiki-template). See [Wiki CLI templates](wiki.md#ecosystem-templates). ## Daily workflow @@ -118,14 +118,14 @@ Do not commit `.agents/skills/` to your wiki repo unless you intentionally vendo ## Next steps -- [Wiki CLI](Wiki_CLI.md) — command reference home +- [wiki](wiki.md) — command reference home - [Wiki Configuration](Wiki_Configuration.md) — tune `wiki`, `graph`, `site`, `link`, and check severities - [Style Guide](Style_Guide.md) — document types, shapes, and wikilinks - [Linked Markdown](Linked_Markdown.md) — the wazootech/linked-markdown protocol specification -- [Wiki Subcommand check](Wiki_Subcommand_check.md) — integrity validation and CI checks -- [Wiki Subcommand lint](Wiki_Subcommand_lint.md) — convention audits (broken links, filenames, headings) -- [Wiki Subcommand query](Wiki_Subcommand_query.md) — ad-hoc SPARQL from the terminal -- [Wiki Subcommand render](Wiki_Subcommand_render.md) — refresh inline SPARQL tables -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md) — local preview and optional SPARQL endpoint -- [Wiki Subcommand build](Wiki_Subcommand_build.md) — static HTML for deployment +- [wiki check](wiki_check.md) — integrity validation and CI checks +- [wiki lint](wiki_lint.md) — convention audits (broken links, filenames, headings) +- [wiki query](wiki_query.md) — ad-hoc SPARQL from the terminal +- [wiki render](wiki_render.md) — refresh inline SPARQL tables +- [wiki serve](wiki_serve.md) — local preview and optional SPARQL endpoint +- [wiki build](wiki_build.md) — static HTML for deployment - [Graph Cache](Graph_Cache.md) — graph reuse and `--cache` diff --git a/docs/wiki/Graph_Cache.md b/docs/wiki/Graph_Cache.md index 1b8b140..1418793 100644 --- a/docs/wiki/Graph_Cache.md +++ b/docs/wiki/Graph_Cache.md @@ -8,8 +8,8 @@ description: In-process RDF graph reuse plus optional on-disk warm-start across Each `wiki` process builds the wiki RDF graph **once** (unless you pass `--reload`) and reuses it for: -- every [Wiki Subcommand query](Wiki_Subcommand_query.md) in that process -- every SPARQL block in [Wiki Subcommand render](Wiki_Subcommand_render.md) +- every [wiki query](wiki_query.md) in that process +- every SPARQL block in [wiki render](wiki_render.md) - `wiki build --render` when rendering before static output OWL-RL expansion runs when inference is enabled (default for most commands; use `--no-inference` on `query` / `render` when debugging asserted triples only). @@ -17,7 +17,7 @@ OWL-RL expansion runs when inference is enabled (default for most commands; use ## Cross-process reuse - By default, a new shell still starts cold. -- Pass `--cache` on [Wiki Subcommand query](Wiki_Subcommand_query.md), [Wiki Subcommand render](Wiki_Subcommand_render.md), or `wiki build --render` to persist a warm graph under `.wiki/cache/`. +- Pass `--cache` on [wiki query](wiki_query.md), [wiki render](wiki_render.md), or `wiki build --render` to persist a warm graph under `.wiki/cache/`. - The persisted graph is reused only when the wiki fingerprint still matches. - `--reload` forces a fresh build and refreshes the current cache entry. @@ -25,7 +25,7 @@ Queries that use SPARQL `GRAPH` clauses build a named-graph dataset instead of t ## Long-lived workflows -[Wiki Subcommand serve](Wiki_Subcommand_serve.md) with `--watch` keeps one process alive. On file changes it rebuilds the graph, re-runs SPARQL rendering, and reloads the browser. +[wiki serve](wiki_serve.md) with `--watch` keeps one process alive. On file changes it rebuilds the graph, re-runs SPARQL rendering, and reloads the browser. ## Tradeoffs @@ -45,6 +45,6 @@ wiki query "..." # same graph as a prior render in one script if yo ## Related -- [Wiki Subcommand query](Wiki_Subcommand_query.md) -- [Wiki Subcommand render](Wiki_Subcommand_render.md) -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md) — long-lived preview and optional [SPARQL endpoint](Wiki_Subcommand_serve.md#sparql-endpoint) +- [wiki query](wiki_query.md) +- [wiki render](wiki_render.md) +- [wiki serve](wiki_serve.md) — long-lived preview and optional [SPARQL endpoint](wiki_serve.md#sparql-endpoint) diff --git a/docs/wiki/JSON_LD.md b/docs/wiki/JSON_LD.md index 78b1a2f..5a34401 100644 --- a/docs/wiki/JSON_LD.md +++ b/docs/wiki/JSON_LD.md @@ -10,13 +10,13 @@ description: JavaScript Object Notation for Linked Data. It is a standard derived from [JSON](JSON.md) that provides a way to serialize [RDF](RDF.md) in JSON format. -The [Wiki CLI](Wiki_CLI.md) can compile wiki contents into JSON-LD using [Wiki Subcommand export](Wiki_Subcommand_export.md). +The [wiki](wiki.md) can compile wiki contents into JSON-LD using [wiki export](wiki_export.md). ## Related - [RDF](RDF.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md#metadata-view) — JSON-LD metadata chip on built pages +- [wiki export](wiki_export.md) +- [wiki serve](wiki_serve.md#metadata-view) — JSON-LD metadata chip on built pages ## References diff --git a/docs/wiki/Jeff_Kazzee.md b/docs/wiki/Jeff_Kazzee.md index 33b2ab1..cd9fc94 100644 --- a/docs/wiki/Jeff_Kazzee.md +++ b/docs/wiki/Jeff_Kazzee.md @@ -32,6 +32,6 @@ familyName: Kazzee ## Related - [Vivary](Vivary.md) -- [Wiki CLI](Wiki_CLI.md) — semantic wiki toolchain (different stack, complementary) +- [wiki](wiki.md) — semantic wiki toolchain (different stack, complementary) - [LLM Wiki](LLM_Wiki.md) — compounding agent-maintained knowledge pattern - [Agent Memory Filesystems](Agent_Memory_Filesystems.md) — filesystem-metaphor memory tools compared diff --git a/docs/wiki/LLM_Wiki.md b/docs/wiki/LLM_Wiki.md index b66b83d..5d9ce61 100644 --- a/docs/wiki/LLM_Wiki.md +++ b/docs/wiki/LLM_Wiki.md @@ -32,11 +32,11 @@ Developer **Farza** (founder of buildspace) created [Farzapedia](Farzapedia.md) ## Integrating the LLM Wiki in this wiki -This [Wiki CLI](Wiki_CLI.md) repository is built directly on the principles of the LLM Wiki design pattern. The wiki grows through two complementary learning modalities — **continual** (temporal accumulation) and **recursive** (iterative self-refinement) — documented in [Learning Systems](Learning_Systems.md). It enforces: +This [wiki](wiki.md) repository is built directly on the principles of the LLM Wiki design pattern. The wiki grows through two complementary learning modalities — **continual** (temporal accumulation) and **recursive** (iterative self-refinement) — documented in [Learning Systems](Learning_Systems.md). It enforces: 1. **Declarative Frontmatter**: Structuring YAML-LD metadata to make pages machine-readable. -1. **Procedural Automation**: Using subcommands like [Wiki Subcommand check](Wiki_Subcommand_check.md) to validate SHACL shapes and JSON Schema frontmatter, and [Wiki Subcommand render](Wiki_Subcommand_render.md) to execute [SPARQL](SPARQL.md) queries dynamically, compiling the graph's intelligence back into static Markdown. +1. **Procedural Automation**: Using subcommands like [wiki check](wiki_check.md) to validate SHACL shapes and JSON Schema frontmatter, and [wiki render](wiki_render.md) to execute [SPARQL](SPARQL.md) queries dynamically, compiling the graph's intelligence back into static Markdown. ## References @@ -44,7 +44,7 @@ This [Wiki CLI](Wiki_CLI.md) repository is built directly on the principles of t ## Related -- [Wiki CLI](Wiki_CLI.md) — including [Wiki CLI templates](Wiki_CLI.md#ecosystem-templates) ([llm-wiki-template](https://github.com/wazootech/llm-wiki-template)) +- [wiki](wiki.md) — including [Wiki CLI templates](wiki.md#ecosystem-templates) ([llm-wiki-template](https://github.com/wazootech/llm-wiki-template)) - [Learning Systems](Learning_Systems.md) — continual versus recursive learning - [Declarative Knowledge](Declarative_Knowledge.md) - [Procedural Knowledge](Procedural_Knowledge.md) diff --git a/docs/wiki/Learning_Systems.md b/docs/wiki/Learning_Systems.md index 4835ded..637f824 100644 --- a/docs/wiki/Learning_Systems.md +++ b/docs/wiki/Learning_Systems.md @@ -6,7 +6,7 @@ description: Continual learning versus recursive learning — how agent-managed # Learning Systems -An [LLM Wiki](LLM_Wiki.md) grows smarter over time through two distinct learning modalities: **continual learning** (temporal accumulation and retention) and **recursive learning** (iterative self-application and refinement). Both are essential to the [Vivary](Vivary.md) agent loop and the [Wiki CLI](Wiki_CLI.md) ecosystem, but they operate at different time scales and target different dimensions of the knowledge base. +An [LLM Wiki](LLM_Wiki.md) grows smarter over time through two distinct learning modalities: **continual learning** (temporal accumulation and retention) and **recursive learning** (iterative self-application and refinement). Both are essential to the [Vivary](Vivary.md) agent loop and the [wiki](wiki.md) ecosystem, but they operate at different time scales and target different dimensions of the knowledge base. ## Continual learning @@ -16,7 +16,7 @@ In this ecosystem, continual learning manifests as: - The **[LLM Wiki](LLM_Wiki.md) pattern** — a persistent, interlinked Markdown corpus that an agent maintains across sessions. Raw inputs are compiled into structured pages; the knowledge base compounds rather than being regenerated each time. - **[Farzapedia](Farzapedia.md)** — Farza's proof-of-concept: 2,500 unstructured entries became ~400 clean, linked wiki articles, then continued to grow and improve. -- **[Wiki CLI](Wiki_CLI.md) validation** — `wiki check` and `wiki lint` ensure each new page meets structural and convention standards, so the corpus stays healthy as it accumulates. +- **[wiki](wiki.md) validation** — `wiki check` and `wiki lint` ensure each new page meets structural and convention standards, so the corpus stays healthy as it accumulates. - **[Agent Memory Filesystems](Agent_Memory_Filesystems.md)** — persistent memory stores (SMFS, MemFS, Wiki CLI) that survive session boundaries and let knowledge accrete. The key property: **knowledge persists and compounds forward**. The agent does not start from zero each session. @@ -29,8 +29,8 @@ In this ecosystem, recursive learning manifests as: - The **[Vivary](Vivary.md) strato loop** — `Ask → retrieve → act → verify → learn → gate`. The "learn" step examines verification results and the gated outcome, then distills improvements into memory, skills, or the graph itself. - **[Vivary ozone](Vivary.md#ozone--review-by-blast-radius)** — graph-aware review that checks not just individual documents but the relationships between them, surfacing gaps a per-document check cannot see. -- **[Procedural Knowledge](Procedural_Knowledge.md)** — self-updating workflows: [SPARQL](SPARQL.md) blocks that [render](Wiki_Subcommand_render.md) live results, [SHACL](SHACL.md) shapes that validate structure, and [wiki skills](Wiki_Skills.md) that encode repeatable processes. -- **[Wiki Subcommand render](Wiki_Subcommand_render.md)** — `wiki render --check` detects stale SPARQL result blocks from a prior run and flags them for regeneration, closing the recursive loop. +- **[Procedural Knowledge](Procedural_Knowledge.md)** — self-updating workflows: [SPARQL](SPARQL.md) blocks that [render](wiki_render.md) live results, [SHACL](SHACL.md) shapes that validate structure, and [wiki skills](Wiki_Skills.md) that encode repeatable processes. +- **[wiki render](wiki_render.md)** — `wiki render --check` detects stale SPARQL result blocks from a prior run and flags them for regeneration, closing the recursive loop. The key property: **the system improves its own process by examining its output**. The loop feeds into itself. @@ -63,4 +63,4 @@ The **[LLM Wiki](LLM_Wiki.md)** pattern is the continual surface; the **[Vivary] - [Declarative Knowledge](Declarative_Knowledge.md) — facts and structures that accumulate - [Procedural Knowledge](Procedural_Knowledge.md) — workflows and processes that self-improve - [Farzapedia](Farzapedia.md) — continual learning proof of concept -- [Wiki Subcommand render](Wiki_Subcommand_render.md) — stale-block detection as recursive feedback +- [wiki render](wiki_render.md) — stale-block detection as recursive feedback diff --git a/docs/wiki/Letta_MemFS.md b/docs/wiki/Letta_MemFS.md index f0b5832..3d894c5 100644 --- a/docs/wiki/Letta_MemFS.md +++ b/docs/wiki/Letta_MemFS.md @@ -39,9 +39,9 @@ description: Coding preferences learned during /init - **Agent-driven hierarchy** — Unlike SMFS’s heavier background graph updates, MemFS relies on the agent (and you, in an editor) to curate structure over time. - **Human-in-the-loop** — Open the memory folder in VS Code or Cursor and edit markdown directly; Git history provides audit and rollback. -## Comparison with [Wiki CLI](Wiki_CLI.md) and [Supermemory SMFS](Supermemory_SMFS.md) +## Comparison with [wiki](wiki.md) and [Supermemory SMFS](Supermemory_SMFS.md) -Choose MemFS when you run **Letta Code** and want Git-auditable, human-editable agent memory with a crisp hot/cold split and an always-on `system/` slice. Choose the [Wiki CLI](Wiki_CLI.md) when you want a **shared, schema-checked wiki** with [Second Brain](Second_Brain.md)-style linking and [semantic web](Semantic_Web.md) tooling independent of a single agent runtime. +Choose MemFS when you run **Letta Code** and want Git-auditable, human-editable agent memory with a crisp hot/cold split and an always-on `system/` slice. Choose the [wiki](wiki.md) when you want a **shared, schema-checked wiki** with [Second Brain](Second_Brain.md)-style linking and [semantic web](Semantic_Web.md) tooling independent of a single agent runtime. For the full cross-tool comparison, see [Agent Memory Filesystems](Agent_Memory_Filesystems.md). diff --git a/docs/wiki/Linked_Markdown.md b/docs/wiki/Linked_Markdown.md index b7d865f..353ba9a 100644 --- a/docs/wiki/Linked_Markdown.md +++ b/docs/wiki/Linked_Markdown.md @@ -97,7 +97,7 @@ The compiled graph can be checked using shape definitions in the wiki: ## Related - [Style Guide](Style_Guide.md) -- [Wiki CLI](Wiki_CLI.md) +- [wiki](wiki.md) - [Wiki Configuration](Wiki_Configuration.md) - [SHACL](SHACL.md) - [RDF](RDF.md) diff --git a/docs/wiki/Microdata.md b/docs/wiki/Microdata.md index aa30df5..4bcbf78 100644 --- a/docs/wiki/Microdata.md +++ b/docs/wiki/Microdata.md @@ -14,7 +14,7 @@ Prefixed CURIEs (`schema:Thing`, `wiki:Page_Name`) in `itemtype`, `itemid`, `ite ## Examples -The [Wiki CLI](Wiki_CLI.md) extracts this format directly from wiki documents into the unified RDF pool: +The [wiki](wiki.md) extracts this format directly from wiki documents into the unified RDF pool:
Microdata in LLM Wiki diff --git a/docs/wiki/N_Quads.md b/docs/wiki/N_Quads.md index 5732595..c2690ca 100644 --- a/docs/wiki/N_Quads.md +++ b/docs/wiki/N_Quads.md @@ -19,7 +19,7 @@ N-Quads is the line-oriented counterpart to [TriG](TriG.md). Where TriG groups t The first line is a triple in the default graph (no graph term). The second assigns the same triple to the named graph `https://example.org/graphs/provenance`. -## In [Wiki CLI](Wiki_CLI.md) +## In [wiki](wiki.md) Use `wiki export -f nquads` when you want RDF serialized as N-Quads. Built pages also expose this view in the Metadata panel under the **NQ** chip. @@ -30,7 +30,7 @@ Use `wiki export -f nquads` when you want RDF serialized as N-Quads. Built pages - [TriG](TriG.md) - [Turtle](Turtle.md) - [JSON LD](JSON_LD.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) +- [wiki export](wiki_export.md) ## References diff --git a/docs/wiki/N_Triples.md b/docs/wiki/N_Triples.md index 591a537..8e97a7a 100644 --- a/docs/wiki/N_Triples.md +++ b/docs/wiki/N_Triples.md @@ -22,7 +22,7 @@ This expresses the RDF statement: - predicate: `https://schema.org/givenName` - object: `Alice` -## In [Wiki CLI](Wiki_CLI.md) +## In [wiki](wiki.md) Use `wiki export -f nt` when you want RDF serialized as N-Triples. Built pages also expose this view in the Metadata panel under the **NT** chip. @@ -33,7 +33,7 @@ Use `wiki export -f nt` when you want RDF serialized as N-Triples. Built pages a - [TriG](TriG.md) - [N Quads](N_Quads.md) - [JSON LD](JSON_LD.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) +- [wiki export](wiki_export.md) ## References diff --git a/docs/wiki/Notation3.md b/docs/wiki/Notation3.md index ab26d99..15263e4 100644 --- a/docs/wiki/Notation3.md +++ b/docs/wiki/Notation3.md @@ -17,7 +17,7 @@ N3 is much more expressive than Turtle; it provides syntax for RDF itself but al - [N Triples](N_Triples.md) - [TriG](TriG.md) - [RDF XML](RDF_XML.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) +- [wiki export](wiki_export.md) ## References diff --git a/docs/wiki/OWL.md b/docs/wiki/OWL.md index 6a9bfcb..8219937 100644 --- a/docs/wiki/OWL.md +++ b/docs/wiki/OWL.md @@ -10,7 +10,7 @@ The **Web Ontology Language (OWL)** is a family of knowledge representation lang OWL adds more vocabulary for describing properties and classes than basic RDF schema, including relations between classes (e.g. disjointness), cardinality (e.g. "exactly one"), equality, richer typing of properties, characteristics of properties (e.g. symmetry), and enumerated classes. -In this wiki, OWL is used by the reasoning engine in the [Wiki CLI](Wiki_CLI.md) to perform deductive expansion of your graph (e.g., using OWL-RL rules). +In this wiki, OWL is used by the reasoning engine in the [wiki](wiki.md) to perform deductive expansion of your graph (e.g., using OWL-RL rules). ## Defining custom RDFS/OWL axioms @@ -43,8 +43,8 @@ The reasoning engine automatically infers and adds the following facts to your g ## Related - [Graph Cache](Graph_Cache.md) — inference defaults and graph reuse -- [Wiki Subcommand query](Wiki_Subcommand_query.md) — `--no-inference` -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint) — `inference=` query parameter +- [wiki query](wiki_query.md) — `--no-inference` +- [wiki serve](wiki_serve.md#sparql-endpoint) — `inference=` query parameter - [RDF](RDF.md) ## References diff --git a/docs/wiki/Obsidian.md b/docs/wiki/Obsidian.md index db3cbd5..44e735b 100644 --- a/docs/wiki/Obsidian.md +++ b/docs/wiki/Obsidian.md @@ -10,4 +10,4 @@ description: A powerful and extensible knowledge base that works on top of a loc ## Integration -For details on running the [Wiki CLI](Wiki_CLI.md) directly from Obsidian, see [Obsidian Integration](Obsidian_Integration.md). +For details on running the [wiki](wiki.md) directly from Obsidian, see [Obsidian Integration](Obsidian_Integration.md). diff --git a/docs/wiki/Obsidian_Integration.md b/docs/wiki/Obsidian_Integration.md index 7ad6be4..125cbdc 100644 --- a/docs/wiki/Obsidian_Integration.md +++ b/docs/wiki/Obsidian_Integration.md @@ -34,7 +34,7 @@ Wiki CLI remains compatible with Obsidian-authored Markdown, but it should not d ## Internal links -This wiki uses Markdown links (`Page_Name.md`). [Obsidian](Obsidian.md) wikis may use wikilinks (`[[Page]]`); the [Wiki CLI](Wiki_CLI.md) still resolves them when filenames follow wiki route rules, and `lint.broken_links` validates that each link resolves. +This wiki uses Markdown links (`Page_Name.md`). [Obsidian](Obsidian.md) wikis may use wikilinks (`[[Page]]`); the [wiki](wiki.md) still resolves them when filenames follow wiki route rules, and `lint.broken_links` validates that each link resolves. ## Related @@ -42,7 +42,7 @@ This wiki uses Markdown links (`Page_Name.md`). [Obsidian](Obsidian.md) wikis ma - [Dataview Integration](Dataview_Integration.md) - [Getting Started](Getting_Started.md) - [Style Guide](Style_Guide.md) -- [Wiki Subcommand check](Wiki_Subcommand_check.md) -- [Wiki Subcommand lint](Wiki_Subcommand_lint.md) -- [Wiki Subcommand render](Wiki_Subcommand_render.md) -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md) — preview with `--watch` +- [wiki check](wiki_check.md) +- [wiki lint](wiki_lint.md) +- [wiki render](wiki_render.md) +- [wiki serve](wiki_serve.md) — preview with `--watch` diff --git a/docs/wiki/Personal_Knowledge.md b/docs/wiki/Personal_Knowledge.md index 94698df..bd83f43 100644 --- a/docs/wiki/Personal_Knowledge.md +++ b/docs/wiki/Personal_Knowledge.md @@ -25,7 +25,7 @@ This is parsed as a typed graph triple (`wiki:gregory wiki:owns wiki:bella`), al ### Built-in structural correctness -Traditional notes suffer from "schema drift" where you forget to add fields like dates or tags. The [Wiki CLI](Wiki_CLI.md) uses **SHACL shapes** and optional **JSON Schema** bindings (`wazoo:jsonSchema`) to audit your notes automatically. This ensures your [second brain](Second_Brain.md) remains consistently structured and complete. +Traditional notes suffer from "schema drift" where you forget to add fields like dates or tags. The [wiki](wiki.md) uses **SHACL shapes** and optional **JSON Schema** bindings (`wazoo:jsonSchema`) to audit your notes automatically. This ensures your [second brain](Second_Brain.md) remains consistently structured and complete. ### Infinite dynamic synthesis (SPARQL) diff --git a/docs/wiki/Procedural_Knowledge.md b/docs/wiki/Procedural_Knowledge.md index c40a815..a41ce9d 100644 --- a/docs/wiki/Procedural_Knowledge.md +++ b/docs/wiki/Procedural_Knowledge.md @@ -12,8 +12,8 @@ In a semantic [Personal Knowledge](Personal_Knowledge.md) wiki, procedural knowl - [Wiki Skills](Wiki_Skills.md) — agent `SKILL.md` workflows for install, scaffold, and wiki audit (repository `skills/`, not indexed as wiki pages) - [SHACL](SHACL.md) shapes and JSON Schema bindings that enforce how pages must be written -- [SPARQL](SPARQL.md) blocks and [Wiki Subcommand render](Wiki_Subcommand_render.md) that refresh tables from the graph -- [Wiki Subcommand check](Wiki_Subcommand_check.md) and [Wiki Subcommand render](Wiki_Subcommand_render.md) pipelines that automate hygiene and synthesis +- [SPARQL](SPARQL.md) blocks and [wiki render](wiki_render.md) that refresh tables from the graph +- [wiki check](wiki_check.md) and [wiki render](wiki_render.md) pipelines that automate hygiene and synthesis An [LLM Wiki](LLM_Wiki.md) pairs declarative frontmatter (facts in the graph) with this procedural layer so notes stay structured and self-updating. @@ -21,8 +21,8 @@ An [LLM Wiki](LLM_Wiki.md) pairs declarative frontmatter (facts in the graph) wi - [Wiki Skills](Wiki_Skills.md) - [Declarative Knowledge](Declarative_Knowledge.md) -- [Wiki Subcommand query](Wiki_Subcommand_query.md) -- [Wiki Subcommand render](Wiki_Subcommand_render.md) -- [Wiki Subcommand check](Wiki_Subcommand_check.md) +- [wiki query](wiki_query.md) +- [wiki render](wiki_render.md) +- [wiki check](wiki_check.md) - [SHACL](SHACL.md) - [SPARQL](SPARQL.md) diff --git a/docs/wiki/Python_API_Reference.md b/docs/wiki/Python_API_Reference.md index 2b996db..d7df0f5 100644 --- a/docs/wiki/Python_API_Reference.md +++ b/docs/wiki/Python_API_Reference.md @@ -15,4 +15,4 @@ The [Wiki Programmatic API](Wiki_Programmatic_API.md) page provides usage exampl ## Related - [Wiki Programmatic API](Wiki_Programmatic_API.md) — usage guide -- [Wiki CLI](Wiki_CLI.md) — command reference +- [wiki](wiki.md) — command reference diff --git a/docs/wiki/RDF.md b/docs/wiki/RDF.md index 171f84d..5758796 100644 --- a/docs/wiki/RDF.md +++ b/docs/wiki/RDF.md @@ -27,7 +27,7 @@ RDF extends the linking structure of the Web to use URIs to name the relationshi ## In this wiki -The [Wiki CLI](Wiki_CLI.md) compiles markdown frontmatter into an RDF graph. Dump serializations with [Wiki Subcommand export](Wiki_Subcommand_export.md) or inspect triples per page in the build/serve metadata view ([Wiki Subcommand serve](Wiki_Subcommand_serve.md#metadata-view)). +The [wiki](wiki.md) compiles markdown frontmatter into an RDF graph. Dump serializations with [wiki export](wiki_export.md) or inspect triples per page in the build/serve metadata view ([wiki serve](wiki_serve.md#metadata-view)). ## References diff --git a/docs/wiki/RDF_XML.md b/docs/wiki/RDF_XML.md index 4635263..d9bfb7e 100644 --- a/docs/wiki/RDF_XML.md +++ b/docs/wiki/RDF_XML.md @@ -29,7 +29,7 @@ This expresses the RDF statement: - predicate: `https://schema.org/givenName` - object: `Alice` -## In [Wiki CLI](Wiki_CLI.md) +## In [wiki](wiki.md) Use `wiki export -f xml` when you want RDF serialized in RDF/XML form. @@ -39,7 +39,7 @@ Use `wiki export -f xml` when you want RDF serialized in RDF/XML form. - [XML](XML.md) - [Turtle](Turtle.md) - [JSON LD](JSON_LD.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) +- [wiki export](wiki_export.md) ## References diff --git a/docs/wiki/Recursive_Semantic_Datasets.md b/docs/wiki/Recursive_Semantic_Datasets.md index b9d8f95..2bee3a5 100644 --- a/docs/wiki/Recursive_Semantic_Datasets.md +++ b/docs/wiki/Recursive_Semantic_Datasets.md @@ -95,5 +95,5 @@ SELECT ?g ?s ?name WHERE { - [Second Brain](Second_Brain.md) - [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) -- [Wiki Subcommand graph](Wiki_Subcommand_graph.md) -- [Wiki Subcommand query](Wiki_Subcommand_query.md) +- [wiki graph](wiki_graph.md) +- [wiki query](wiki_query.md) diff --git a/docs/wiki/SHACL.md b/docs/wiki/SHACL.md index ae0405c..0b23f7d 100644 --- a/docs/wiki/SHACL.md +++ b/docs/wiki/SHACL.md @@ -8,7 +8,7 @@ description: Shapes Constraint Language for validating RDF graphs. The **Shapes Constraint Language (SHACL)** is a W3C recommendation for validating [RDF](RDF.md) graphs against a set of conditions. These conditions are provided as shapes and other constructs expressed in the form of an RDF graph itself. -In this wiki, SHACL is used to enforce structure via the [Wiki CLI](Wiki_CLI.md) validation engine. +In this wiki, SHACL is used to enforce structure via the [wiki](wiki.md) validation engine. ## Defining custom SHACL shapes (validation) @@ -69,8 +69,8 @@ Pure `.ttl` or `.trig` files in `shapes/` also load when that directory is liste ## Related -- [Wiki Subcommand check](Wiki_Subcommand_check.md) — PySHACL and JSON Schema frontmatter validation -- [Wiki Subcommand lint](Wiki_Subcommand_lint.md) — prose and link conventions (separate from shapes) +- [wiki check](wiki_check.md) — PySHACL and JSON Schema frontmatter validation +- [wiki lint](wiki_lint.md) — prose and link conventions (separate from shapes) - [Style Guide](Style_Guide.md) — shape authoring and filenames - [Software Application Shape](Software_Application_Shape.md) — example `sh:NodeShape` - [Wiki Configuration](Wiki_Configuration.md) — `wiki.inputs` and shapes layout diff --git a/docs/wiki/SPARQL.md b/docs/wiki/SPARQL.md index 9183005..92e225e 100644 --- a/docs/wiki/SPARQL.md +++ b/docs/wiki/SPARQL.md @@ -8,11 +8,11 @@ description: Standard query language and protocol for RDF. **SPARQL** (Recursive acronym for SPARQL Protocol and RDF Query Language) is an [RDF](RDF.md) query language—that is, a semantic query language for databases—able to retrieve and manipulate data stored in RDF format. -In the [Wiki CLI](Wiki_CLI.md), SPARQL powers [Wiki Subcommand query](Wiki_Subcommand_query.md), inline tables refreshed by [Wiki Subcommand render](Wiki_Subcommand_render.md), and (when enabled) a read-only HTTP endpoint on [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint). +In the [wiki](wiki.md), SPARQL powers [wiki query](wiki_query.md), inline tables refreshed by [wiki render](wiki_render.md), and (when enabled) a read-only HTTP endpoint on [wiki serve](wiki_serve.md#sparql-endpoint). ## Common prefixes -The [Wiki CLI](Wiki_CLI.md) automatically binds your namespace prefixes dynamically from the `wiki.yaml` file. The primary prefix mappings are: +The [wiki](wiki.md) automatically binds your namespace prefixes dynamically from the `wiki.yaml` file. The primary prefix mappings are: - **`schema:`** `https://schema.org/` (Standard schema vocabulary) - **`wiki:`** `https://wazootech.github.io/wiki/wiki/` (Your local wiki namespace) @@ -76,10 +76,10 @@ ORDER BY ?class ## Related -- [Wiki Subcommand query](Wiki_Subcommand_query.md) — ad-hoc queries from the terminal -- [Wiki Subcommand render](Wiki_Subcommand_render.md) — refresh inline SPARQL result tables in markdown -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint) — optional read-only HTTP endpoint on `wiki serve` -- [wiki-yasgui-template](https://github.com/wazootech/wiki-yasgui-template) — external YASGUI template repository ([Wiki CLI templates](Wiki_CLI.md#ecosystem-templates)) +- [wiki query](wiki_query.md) — ad-hoc queries from the terminal +- [wiki render](wiki_render.md) — refresh inline SPARQL result tables in markdown +- [wiki serve](wiki_serve.md#sparql-endpoint) — optional read-only HTTP endpoint on `wiki serve` +- [wiki-yasgui-template](https://github.com/wazootech/wiki-yasgui-template) — external YASGUI template repository ([Wiki CLI templates](wiki.md#ecosystem-templates)) - [Style Guide](Style_Guide.md) — `sparql:start` / `sparql:end` block conventions ## References diff --git a/docs/wiki/Semantic_Web.md b/docs/wiki/Semantic_Web.md index 07344d5..f62aca8 100644 --- a/docs/wiki/Semantic_Web.md +++ b/docs/wiki/Semantic_Web.md @@ -28,7 +28,7 @@ By adding semantic metadata to content, search engines and agents can perform re ## Related - [LLM Wiki](LLM_Wiki.md) — applied pattern in this repository -- [Wiki CLI](Wiki_CLI.md) — wiki tooling built on this stack +- [wiki](wiki.md) — wiki tooling built on this stack ## References diff --git a/docs/wiki/Style_Guide.md b/docs/wiki/Style_Guide.md index fbb3e26..190d1f8 100644 --- a/docs/wiki/Style_Guide.md +++ b/docs/wiki/Style_Guide.md @@ -6,14 +6,14 @@ description: Canonical rules for wiki filenames, links, prose, frontmatter, shap # Style Guide -This is the **canonical style guide** for authoring pages in an [LLM Wiki](LLM_Wiki.md) wiki. [Wiki Subcommand check](Wiki_Subcommand_check.md) and [Wiki Subcommand lint](Wiki_Subcommand_lint.md) enforce the machine-checkable rules; prose conventions below are documented for contributors and agents alike. +This is the **canonical style guide** for authoring pages in an [LLM Wiki](LLM_Wiki.md) wiki. [wiki check](wiki_check.md) and [wiki lint](wiki_lint.md) enforce the machine-checkable rules; prose conventions below are documented for contributors and agents alike. In **this repository**, [AGENTS.md](https://github.com/wazootech/wiki/blob/main/AGENTS.md) is a thin companion: it maps rules to `check:*` / `lint:*` auditors, lists architecture notes for the CLI codebase, and shows CI commands. Do not duplicate wiki-authoring prose here—link here instead. ## File layout - Put pages under directories listed in `wiki.inputs` (usually `wiki/`). -- **Prefer Wikipedia-style filenames** — preserved capitalization and underscores, for example `Gregory_Davidson.md`, `Wiki_CLI.md`, and `JSON_LD.md`. Do not use lowercase kebab-case such as `gregory-house.md` unless your project explicitly chooses that convention in `wiki.filename_pattern`. +- **Prefer Wikipedia-style filenames** — preserved capitalization and underscores, for example `Gregory_Davidson.md`, `LLM_Wiki.md`, and `JSON_LD.md`. Do not use lowercase kebab-case such as `gregory-house.md` unless your project explicitly chooses that convention in `wiki.filename_pattern`. - Avoid spaces and other unsafe route characters in page paths. - Use `index.md` only for folder index routes (for example `wiki/games/index.md` → `/wiki/games/`). - Filenames are the source of truth for page IDs — no explicit `id:` frontmatter is required unless you intentionally override routing. @@ -97,7 +97,7 @@ Inline SPARQL blocks use `<!-- sparql:start -->` … `<!-- sparql:end - ## SHACL shapes -Define constraints in frontmatter with `type: sh:NodeShape` (see `wiki init`'s `Person_Shape.md` or [Software Application Shape](Software_Application_Shape.md) in this wiki). Shapes in the wiki are loaded into the validation graph; [Wiki Subcommand check](Wiki_Subcommand_check.md) runs PySHACL against every document. Background: [SHACL](SHACL.md). +Define constraints in frontmatter with `type: sh:NodeShape` (see `wiki init`'s `Person_Shape.md` or [Software Application Shape](Software_Application_Shape.md) in this wiki). Shapes in the wiki are loaded into the validation graph; [wiki check](wiki_check.md) runs PySHACL against every document. Background: [SHACL](SHACL.md). Optionally bind a **JSON Schema** on the same shape document with `wazoo:jsonSchema` (local path under the wiki config root or remote `http(s)` URL). Type-level schemas apply to every page whose effective `type` matches `sh:targetClass`. Pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list); all bound schemas must pass. @@ -162,7 +162,7 @@ ORDER BY ?class -Use `wiki render --check` in CI to fail when blocks are stale. See [Wiki Subcommand render](Wiki_Subcommand_render.md) and [Graph Cache](Graph_Cache.md). +Use `wiki render --check` in CI to fail when blocks are stale. See [wiki render](wiki_render.md) and [Graph Cache](Graph_Cache.md). ## HTML [microdata](Microdata.md) @@ -170,14 +170,14 @@ The parser reads `itemscope` / `itemtype` / `itemprop` in markdown bodies and ad ## Page layouts (HTML) -For [Wiki Subcommand build](Wiki_Subcommand_build.md) and [Wiki Subcommand serve](Wiki_Subcommand_serve.md), set `wazoo:layout` to a page layout path (for example `layouts/article.html`) to override the site default for that page. Omit it to use `site.layout` from `wiki.yml` or `wiki.yaml`. See [Wiki Page Layouts](Wiki_Page_Layouts.md). Infobox values like `wiki:Other_Page` still link when that page exists. +For [wiki build](wiki_build.md) and [wiki serve](wiki_serve.md), set `wazoo:layout` to a page layout path (for example `layouts/article.html`) to override the site default for that page. Omit it to use `site.layout` from `wiki.yml` or `wiki.yaml`. See [Wiki Page Layouts](Wiki_Page_Layouts.md). Infobox values like `wiki:Other_Page` still link when that page exists. ## Related - [Linked Markdown](Linked_Markdown.md) — protocol specification - [SHACL](SHACL.md) — shapes language background - [SPARQL](SPARQL.md) — query language background -- [Wiki Subcommand query](Wiki_Subcommand_query.md) — ad-hoc SPARQL -- [Wiki Subcommand render](Wiki_Subcommand_render.md) — inline SPARQL tables -- [Wiki Subcommand export](Wiki_Subcommand_export.md) — dump frontmatter as RDF +- [wiki query](wiki_query.md) — ad-hoc SPARQL +- [wiki render](wiki_render.md) — inline SPARQL tables +- [wiki export](wiki_export.md) — dump frontmatter as RDF - [Design Philosophies](Design_Philosophies.md) — CLI output conventions (not wiki prose) diff --git a/docs/wiki/Supermemory_SMFS.md b/docs/wiki/Supermemory_SMFS.md index 5d3db52..8aee365 100644 --- a/docs/wiki/Supermemory_SMFS.md +++ b/docs/wiki/Supermemory_SMFS.md @@ -41,9 +41,9 @@ Files under configured **memory paths** (for example `user.md`, `memory.md`, or - **`profile.md`** — Virtual root file: a live, token-lean digest of the container the agent can `cat` instead of walking every subtree. - **Multi-modal** — PDFs, images, and other types can be ingested; text representations become searchable through the same shell tools. -## Comparison with [Wiki CLI](Wiki_CLI.md) and [Letta MemFS](Letta_MemFS.md) +## Comparison with [wiki](wiki.md) and [Letta MemFS](Letta_MemFS.md) -Choose SMFS when you want **semantic search hidden behind bash**, multi-platform sync, integrations, and managed scale without maintaining a wiki toolchain. Choose the [Wiki CLI](Wiki_CLI.md) when you want **explicit, inspectable [Declarative Knowledge](Declarative_Knowledge.md)**, [Procedural Knowledge](Procedural_Knowledge.md) via `wiki check` / `wiki render`, and a compounding markdown codebase under your control. +Choose SMFS when you want **semantic search hidden behind bash**, multi-platform sync, integrations, and managed scale without maintaining a wiki toolchain. Choose the [wiki](wiki.md) when you want **explicit, inspectable [Declarative Knowledge](Declarative_Knowledge.md)**, [Procedural Knowledge](Procedural_Knowledge.md) via `wiki check` / `wiki render`, and a compounding markdown codebase under your control. For the full cross-tool comparison, see [Agent Memory Filesystems](Agent_Memory_Filesystems.md). diff --git a/docs/wiki/TriG.md b/docs/wiki/TriG.md index 4658ca3..bb4a640 100644 --- a/docs/wiki/TriG.md +++ b/docs/wiki/TriG.md @@ -24,7 +24,7 @@ GRAPH { The first triple lives in the default graph; the second appears in the named graph `https://example.org/graphs/provenance`. -## In [Wiki CLI](Wiki_CLI.md) +## In [wiki](wiki.md) Use `wiki export -f trig` when you want RDF serialized as TriG. Built pages also expose this view in the Metadata panel under the **TriG** chip. @@ -35,7 +35,7 @@ Use `wiki export -f trig` when you want RDF serialized as TriG. Built pages also - [N Triples](N_Triples.md) - [N Quads](N_Quads.md) - [Notation3](Notation3.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) +- [wiki export](wiki_export.md) ## References diff --git a/docs/wiki/Turtle.md b/docs/wiki/Turtle.md index e5ce3ca..ebda92d 100644 --- a/docs/wiki/Turtle.md +++ b/docs/wiki/Turtle.md @@ -19,7 +19,7 @@ It is a subset of [Notation3](Notation3.md) and a superset of the minimal [N Tri - [Notation3](Notation3.md) - [TriG](TriG.md) - [JSON LD](JSON_LD.md) -- [Wiki Subcommand export](Wiki_Subcommand_export.md) +- [wiki export](wiki_export.md) ## References diff --git a/docs/wiki/Vivary.md b/docs/wiki/Vivary.md index 693ba0b..9f95915 100644 --- a/docs/wiki/Vivary.md +++ b/docs/wiki/Vivary.md @@ -183,9 +183,9 @@ Most workspaces never need exo. Single-agent setups stop at **tropo + strato**. - **No lock-in.** Plain Markdown + YAML; [Obsidian](Obsidian.md), Claude Code, Codex, or no editor at all. - **Medium-agnostic.** The same graph and review serve code and prose. -## Vivary vs [Wiki CLI](Wiki_CLI.md) +## Vivary vs [wiki](wiki.md) -| Dimension | Vivary (tropo) | [Wiki CLI](Wiki_CLI.md) | +| Dimension | Vivary (tropo) | [wiki](wiki.md) | | --------------- | ---------------------------------------------- | ---------------------------------------- | | Primary goal | Standardized **agent workspace** | Semantic wiki **toolchain** | | Schema model | Folder-as-type + `tropo.toml` packs | SHACL, JSON Schema, `wiki.yaml` | @@ -212,7 +212,7 @@ Vivary composes ideas from [Jeff Kazzee](Jeff_Kazzee.md)'s earlier tools: ## Related - [Jeff Kazzee](Jeff_Kazzee.md) — author and tool lineage -- [Wiki CLI](Wiki_CLI.md) — semantic compiler for Markdown wikis +- [wiki](wiki.md) — semantic compiler for Markdown wikis - [LLM Wiki](LLM_Wiki.md) — compounding agent-maintained knowledge pattern - [Agent Memory Filesystems](Agent_Memory_Filesystems.md) — filesystem-metaphor memory tools compared - [Obsidian](Obsidian.md) — optional authoring surface (`create-vivary init --obsidian`) diff --git a/docs/wiki/WikiThon.md b/docs/wiki/WikiThon.md index 55f5156..04b6f1f 100644 --- a/docs/wiki/WikiThon.md +++ b/docs/wiki/WikiThon.md @@ -23,7 +23,7 @@ It rode the same cultural moment as the [LLM Wiki](LLM_Wiki.md) pattern (Andrej Participants were asked to build systems that reason over **long context**, **memory**, and **workflows**—not shallow prompt wrappers. The sponsored substrate was [HydraDB](https://docs.hydradb.com/get-started/introduction), a unified context layer for agents (ingest documents and memories, recall ranked context via APIs such as `full_recall`, then ground an LLM on the result). -That complements file-first wikis like those described in [Personal Knowledge](Personal_Knowledge.md): HydraDB emphasizes managed recall and graph-backed context, while the [Wiki CLI](Wiki_CLI.md) supports markdown + RDF + [SHACL](SHACL.md) and JSON Schema validation for static, inspectable wikis. +That complements file-first wikis like those described in [Personal Knowledge](Personal_Knowledge.md): HydraDB emphasizes managed recall and graph-backed context, while the [wiki](wiki.md) supports markdown + RDF + [SHACL](SHACL.md) and JSON Schema validation for static, inspectable wikis. ## Prizes and community @@ -32,5 +32,5 @@ The [Luma page](https://luma.com/6pybuh79) advertised roughly **$800** in prizes ## See also - [LLM Wiki](LLM_Wiki.md) — design pattern and primary sources -- [Farzapedia](Farzapedia.md) — reference personal [wiki build](Wiki_Subcommand_build.md) +- [Farzapedia](Farzapedia.md) — reference personal [wiki build](wiki_build.md) - [Obsidian Integration](Obsidian_Integration.md) — common viewer for markdown wikis diff --git a/docs/wiki/Wiki_CLI.md b/docs/wiki/Wiki_CLI.md index 6ecca04..eec6795 100644 --- a/docs/wiki/Wiki_CLI.md +++ b/docs/wiki/Wiki_CLI.md @@ -1,319 +1,7 @@ --- -type: schema:SoftwareApplication -name: Wiki CLI -softwareVersion: 0.1.21 -description: Command-line interface for querying, validating, and publishing semantic markdown wikis. -codeRepository: https://github.com/wazootech/wiki +type: TechArticle +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki --- - -# Wiki CLI - -This page is the **documentation home** for **Wiki CLI** (`wiki` on PyPI and npm as [**`wazootech-wiki`**](https://pypi.org/project/wazootech-wiki/)): the semantic knowledge **toolchain** for Markdown wikis — validate with [SHACL](SHACL.md) and JSON Schema, infer and query with [SPARQL](SPARQL.md), and publish static HTML. It compiles wikis into RDF and sits **beneath** note apps and LLM-assisted workflows — progressive enhancement, not a migration. - -```bash -pip install wazootech-wiki -wiki --help -``` - -Install options: PyPI (`pip install wazootech-wiki`), npm ([`wazootech-wiki` on npm](https://www.npmjs.com/package/wazootech-wiki) → `wiki` on PATH), or zero-install (`npx wazootech-wiki` / `uvx wazootech-wiki` — same subcommands as `wiki`). See [Getting Started](Getting_Started.md#install). - -## Quickstart - -```bash -pip install wazootech-wiki -mkdir my-wiki && cd my-wiki -wiki init -wiki check -wiki lint -wiki serve -``` - -See [Getting Started](Getting_Started.md) for a full walkthrough. - -## What wiki is - -- The **compiler / validator / query engine** for Markdown knowledge bases with semantic frontmatter -- An **OOTB wiki builder** — links, navigation, SHACL and JSON Schema checks, SPARQL, and static HTML from a folder of `.md` files -- A **memory layer** — ingest or watch an existing wiki without owning the editor -- **Interop-first** — works alongside [Obsidian](Obsidian_Integration.md), [LLM Wiki](LLM_Wiki.md) setups, and any Markdown editor - -Adoption path: `wiki init` → `wiki check` → `wiki serve`, then add `lint`, `query`, `render`, and `build` as the wiki matures. - -Wiki CLI is intentionally batteries-included for semantic Markdown wikis: validation, formatting, querying, rendering, exporting, building, and local preview belong together. The boundary is not "minimal CLI only"; the boundary is "semantic wiki toolchain, not editor/app automation." - -## What wiki is not - -- The **primary editor** or daily note-taking surface -- A **replacement** for Obsidian, Logseq, or another wiki UI -- A **note app clone**, CMS, or authenticated multi-user web product -- An **auth layer** — local-first CLI and static publish; see deferred scope in [Wiki CLI templates](#ecosystem-templates) below -- A vault automation CLI for daily notes, note append/read workflows, task lists, tags, plugin development, or Obsidian app control -- A replacement for shell tools, Git, Pandoc, or editor-native commands - -Humans and agents keep writing where they already write. `wiki` makes that content **trustworthy** (SHACL, JSON Schema, and conventions), **searchable** (SPARQL + OWL-RL), and **publishable** (static HTML, JSON-LD, Turtle, optional read-only SPARQL over `wiki serve`). - -## Memory layer and ingestion - -Rather than owning your editor or data store, **Wiki** functions as a **read-only memory layer** over your wiki. It parses, indexes, and queries the Markdown documents on your filesystem without mutating them or locking you into a proprietary format. - -- **Ingestion:** The CLI reads YAML/JSON frontmatter and HTML microdata from your files, compiling them into an in-memory RDF graph that can be queried with SPARQL or verified against SHACL shapes and JSON Schema bindings. -- **Watching:** Running `wiki serve --watch` instructs the CLI to watch the wiki directory. Any edits you make in your preferred editor are immediately processed, updating the graph in the background and keeping your preview server synchronized. - -## Toolchain vs authoring surface - -| Layer | Role | Examples | -| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------- | -| Authoring surface | Create, edit, search, and organize notes | Obsidian CLI, Obsidian, VS Code, shell | -| Wiki CLI semantic layer | Compile wiki → RDF graph; check, lint, fmt; query; render; build/serve | `wiki check`, `wiki query`, `wiki build` | -| Existing primitives | History, sync, print/PDF, and generic text processing | Git, shell tools, Pandoc | -| Outputs | Deployable semantic artifacts | GitHub Pages HTML, export files, `/api/sparql` when enabled | - -This separation is intentional: the strongest differentiator is the **machine layer** (SHACL, OWL-RL, SPARQL, typed HTML) that most note apps do not provide. **Wiki** avoids competing with editor-centric tools while making incremental adoption obvious. - -When an existing primitive already owns a workflow, Wiki CLI integrates rather than replaces it. Obsidian CLI owns Obsidian app/vault automation; Git owns history and collaboration; shell tools own generic file/process composition; Pandoc and document tools own non-semantic document conversion. - -`wiki link --fix-broken` supports link hygiene for publishable wikis. `wiki link --apply` is optional wiki-gardening: useful when desired, but not required for validation, publishing, or Obsidian compatibility. - -## Interop-first workflows - -### Obsidian - -Run `wiki` against the folder that contains `wiki.yml` or `wiki.yaml`. Use Shell Commands for on-save `wiki check`, hotkey `wiki render`, or `wiki serve --watch` for preview. Details: [Obsidian integration](Obsidian_Integration.md) and [Dataview integration](Dataview_Integration.md). - -### LLM wikis - -Treat the wiki as a compounding codebase agents maintain over time. Structured frontmatter and link conventions make SPARQL and SHACL meaningful on agent output. Pattern overview: [LLM Wiki](LLM_Wiki.md). - -### Plain Markdown - -No Obsidian or agent stack required. `wiki init` scaffolds a wiki; conventions are documented in [Style Guide](Style_Guide.md). - -## Three capabilities of the CLI - -| Capability | Commands | Value | -| ------------ | ---------------------------------- | ------------------------------------------------------------------ | -| Trust | `check`, `lint`, `fmt` | Integrity contracts and authoring conventions | -| Intelligence | `query`, `mcp`, `render`, `export` | SPARQL, MCP graph access, inline result blocks, RDF serializations | -| Publish | `build`, `serve`, `link` | Static site, local preview, wikilink hygiene | -| Sources | `install`, `update`, `remove` | Fetch, lock, update, and manage external sources | -| Provenance | `graph list` | Inspect read-only named graph boundaries | - -Design rationale for silence, pipes, and flat subcommands: [Design philosophies](Design_Philosophies.md). - -## Ecosystem templates - -GitHub **template repositories** in the [wazootech](https://github.com/wazootech) org sit at the edges of the toolchain — publish surfaces, query UIs, and starter vaults — while Wiki CLI owns the semantic layer ([Design philosophies](Design_Philosophies.md)). This section is the canonical registry. - -| Template | Description | -| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [wiki-template](https://github.com/wazootech/wiki-template) | Generic Wiki CLI project (`wiki init` parity plus deploy) | -| [wiki-yasgui-template](https://github.com/wazootech/wiki-yasgui-template) | SPARQL query editor UI (YASGUI); `wiki serve` `/api/sparql`, export TTL ([#14](https://github.com/wazootech/wiki/issues/14), [#81](https://github.com/wazootech/wiki/issues/81)) | -| [llm-wiki-template](https://github.com/wazootech/llm-wiki-template) | [LLM Wiki](LLM_Wiki.md) starter vault with agent-oriented pages and gardening hooks ([#83](https://github.com/wazootech/wiki/issues/83)) | -| [wiki-nextjs-template](https://github.com/wazootech/wiki-nextjs-template) | Next.js SSG consumer of `wiki export` JSON-LD ([#15](https://github.com/wazootech/wiki/issues/15)) | -| [wiki-quartz-template](https://github.com/wazootech/wiki-quartz-template) | Quartz static site from a compatible vault plus `wiki check` CI ([#16](https://github.com/wazootech/wiki/issues/16)); Obsidian remains a supported authoring surface — the slug does not include `obsidian` | -| [wiki-mintlify-template](https://github.com/wazootech/wiki-mintlify-template) | Mintlify or Holocron docs site from a compatible vault ([#31](https://github.com/wazootech/wiki/issues/31)) | -| [wiki-astro-template](https://github.com/wazootech/wiki-astro-template) | Astro SSG consumer of `wiki export` JSON-LD ([#96](https://github.com/wazootech/wiki/issues/96)) | - -### Artifact contract - -External templates consume Wiki CLI outputs — they do not replace the compiler: - -- **`wiki.yml`** / **`wiki.yaml`** — config root; `wiki.inputs`, `graph.*`, `site.*` -- **`wiki export`** — JSON-LD, Turtle, TriG, and other RDF serializations -- **`wiki build`** — static HTML under `site.base_url` - -### Retired slugs - -Do not use these in new prose: `sparql-service-template` (→ `wiki-yasgui-template`); `wiki-virtuoso-template` (→ folded into `wiki-yasgui-template`); `wiki-obsidian-quartz-template`, `obsidian-quartz-template` (→ `wiki-quartz-template`); bare `nextjs-template`, `mintlify-template`, `astro-template` (→ `wiki-*` counterparts). - -## Features - -- **Check** — SHACL and JSON Schema integrity, route safety, layout frontmatter ([Wiki Subcommand check](Wiki_Subcommand_check.md)) -- **Lint** — broken links, filename pattern, and heading conventions ([Wiki Subcommand lint](Wiki_Subcommand_lint.md)) -- **Link** — repair broken internal links and optionally insert suggested links as wiki-gardening ([Wiki Subcommand link](Wiki_Subcommand_link.md)) -- **Fmt** — mdformat for markdown ([Wiki Subcommand fmt](Wiki_Subcommand_fmt.md)) -- **Query** — SPARQL with OWL-RL and optional `--pretty` Rich tables ([Wiki Subcommand query](Wiki_Subcommand_query.md), [Graph Cache](Graph_Cache.md)) -- **Graph list** — inspect root and source named graphs for SPARQL `GRAPH` provenance ([Wiki Subcommand graph](Wiki_Subcommand_graph.md)) -- **MCP** — read-only query-first MCP server for local agents ([Wiki Subcommand mcp](Wiki_Subcommand_mcp.md)) -- **Render** — live tables from inline SPARQL ([Wiki Subcommand render](Wiki_Subcommand_render.md)) -- **Build / serve** — static site, local preview, and optional read-only SPARQL endpoint ([Wiki Subcommand build](Wiki_Subcommand_build.md), [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint)) -- **Export** — JSON-LD and RDF serializations ([Wiki Subcommand export](Wiki_Subcommand_export.md)) -- **Install** — fetch and lock external data sources ([Wiki Subcommand install](Wiki_Subcommand_install.md)) -- **Update** — check locked sources for newer commits ([Wiki Subcommand update](Wiki_Subcommand_update.md)) -- **Remove** — delete a source from wiki.yml, cache, and lockfile ([Wiki Subcommand remove](Wiki_Subcommand_remove.md)) -- **Init** — scaffold `wiki.yml` ([Wiki Subcommand init](Wiki_Subcommand_init.md)) -- **Upgrade** — PyPI updates ([Wiki Subcommand upgrade](Wiki_Subcommand_upgrade.md)) - -## Supported file formats - -### Input pipelines - -Wiki CLI processes files through two distinct pipelines. Files in `wiki.inputs` are classified as either **documents** (frontmatter parsed, IRI derived from file path, link-checked) or **raw RDF sources** (loaded directly via rdflib, no document processing): - -| Category | Extensions | Pipeline | Key behavior | -| ------------------- | -------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- | -| Wiki documents | `.md`, `.yaml`, `.yml`, `.json`, `.toml` | Frontmatter → graph | Parsed for frontmatter/data; document IRI derived from file path; link-checked and exportable | -| Data-only documents | `.yaml`, `.yml`, `.json`, `.toml` | Frontmatter → graph | Subset of wiki documents without a markdown body — entire file is the data dict | -| Raw RDF sources | `.ttl`, `.trig`, `.nt`, `.nq`, `.rdf`, `.xml`, `.jsonld` | rdflib parse → graph | Loaded as raw triples; no route, no link checking, no frontmatter pipeline | -| Inline Turtle | Inside `.md` as ```` ```turtle ```` blocks | rdflib parse → graph | Fenced turtle blocks inside markdown files are parsed and merged into the graph | - -### Document pipeline - -Markdown files are parsed via the [Linked Markdown](Linked_Markdown.md) protocol: the YAML/JSON frontmatter between `---` delimiters is extracted as the data dict, and the body text is optionally added to the graph via `content_predicate`. Data-only documents (`.yaml`, `.yml`, `.json`, `.toml`) skip the body split — the entire file is the data. - -All document formats have their `@context` auto-populated with `wiki:` and `foaf:` default prefixes if none is present. An explicit `@id` or `id` key in frontmatter overrides the file-path-based IRI ([Linked Markdown](Linked_Markdown.md#subject-uri-resolution)). - -### Raw RDF pipeline - -Files with raw RDF extensions are parsed directly by rdflib using the format mapped from their extension. They bypass all document processing — no route registration, no link validation, no frontmatter coercion. They contribute triples to the same graph but are invisible to `wiki export` (which operates on documents) and `wiki link`. - -**Important nuance:** `.jsonld` is raw RDF (rdflib `json-ld` format) — it is NOT a wiki document. It does not get a document IRI, does not go through `ensure_context()`, and is not subject to link checking. A `.json` file with the same content *is* a wiki document and follows the frontmatter pipeline. These are disjoint processing paths. - -### Output formats - -| Context | Formats | -| ----------------------------------------- | -------------------------------------------------------------------------- | -| `wiki export` | `dict` (default), `json-ld`, `turtle`, `xml`, `n3`, `nt`, `trig`, `nquads` | -| `wiki query` | `table` (default), `json`, `csv`, `tsv`, `turtle`, `n3`, `markdown` | -| `wiki serve` / `wiki build` metadata view | `json-ld`, `turtle`, `n3`, `xml`, `nt`, `trig`, `nquads` | - -### Key nuances - -- **`.jsonld` vs `.json`** — Different pipelines for the same data shape. See raw RDF pipeline note above. -- **N3 is output-only** — Notation3 (`.n3`) is available for `wiki export` and `wiki query` CONSTRUCT results but is not recognized as an input graph source extension. -- **`@context` auto-injection** — Document files that lack an `@context` key get default `wiki:` and `foaf:` prefixes injected. If `@context` is present as a dict, those defaults are merged in. -- **Only `.md` carries body text** — Data-only formats cannot carry a body literal in the graph; the entire file content is the data dict. -- **Inline ```` ```turtle ``` ```` blocks** — Any fenced code block with `turtle` language inside a `.md` file is parsed as Turtle RDF and merged into the wiki graph. This is separate from SPARQL result blocks. -- **`.toml` is a document format** — TOML files under `wiki.inputs` are treated as data-only wiki documents, subject to `@context` injection and route generation. - -### Related - -- [Linked Markdown](Linked_Markdown.md) — document-to-RDF protocol and IRI resolution -- [RDF](RDF.md) — RDF data model and serialization references -- Individual format pages: [Turtle](Turtle.md), [TriG](TriG.md), [N-Triples](N_Triples.md), [N-Quads](N_Quads.md), [RDF/XML](RDF_XML.md), [Notation3](Notation3.md), [JSON-LD](JSON_LD.md) - -## Agent skills - -Procedural knowledge for coding agents: [Wiki Skills](Wiki_Skills.md) (`skills/wiki/` in the repository). - -## Start here - -- [Getting Started](Getting_Started.md) — install, `wiki init`, first `check` and `serve` -- [Wiki Configuration](Wiki_Configuration.md) — `wiki.yml` / `wiki.yaml` options -- [Style Guide](Style_Guide.md) — frontmatter, shapes, internal links, SPARQL blocks -- [Graph Cache](Graph_Cache.md) — in-process RDF graph reuse -- [Design Philosophies](Design_Philosophies.md) — silence is golden, pipes, flat commands - -## Global Options - -These options apply to config-loading subcommands (`check`, `lint`, `link`, `query`, `mcp`, `render`, `build`, `export`, `serve`, `fmt`, `install`, `remove`). `init` and `upgrade` do not load a config file. - -### `-c, --config PATH` - -Path to `wiki.yml`, `wiki.yaml`, `wiki.json`, or a directory containing one of those files. Defaults to the current directory (`.`). - -Example: - -```bash -wiki -c docs/wiki.yml check -``` - -### `--wiki-inputs PATH` (repeatable) - -Override or extend `wiki.inputs` from config for a single invocation. Relative paths resolve against the config file directory. Useful for one-off queries against a subdirectory. - -Example: - -```bash -wiki --wiki-inputs ./wiki --wiki-inputs ./imported query "SELECT * WHERE { ?s ?p ?o } LIMIT 5" -``` - -## Command reference - -Each subcommand has a dedicated page: - - - -| command | description | -| --- | --- | -| [Wiki_Subcommand_build](Wiki_Subcommand_build.md) | Generate a static HTML site from the wiki. | -| [Wiki_Subcommand_check](Wiki_Subcommand_check.md) | Integrity checks — SHACL validation, JSON Schema frontmatter, route safety, and layout frontmatter. | -| [Wiki_Subcommand_export](Wiki_Subcommand_export.md) | Export document frontmatter as RDF or JSON-LD. | -| [Wiki_Subcommand_fmt](Wiki_Subcommand_fmt.md) | Format markdown wiki pages using mdformat with wikilink preservation. | -| [Wiki_Subcommand_graph](Wiki_Subcommand_graph.md) | List read-only RDF named graphs for root and installed source provenance. | -| [Wiki_Subcommand_init](Wiki_Subcommand_init.md) | Scaffold wiki.yml and starter wiki pages interactively. | -| [Wiki_Subcommand_install](Wiki_Subcommand_install.md) | Fetch and lock external data sources declared in wiki.yml. | -| [Wiki_Subcommand_link](Wiki_Subcommand_link.md) | Suggest missing wikilinks and repair unambiguous broken internal links. | -| [Wiki_Subcommand_lint](Wiki_Subcommand_lint.md) | Convention audits for broken links, filename patterns, heading style, and internal link style. | -| [Wiki_Subcommand_mcp](Wiki_Subcommand_mcp.md) | Run a read-only MCP server for querying the wiki graph. | -| [Wiki_Subcommand_query](Wiki_Subcommand_query.md) | Run SPARQL SELECT or CONSTRUCT against the wiki graph. | -| [Wiki_Subcommand_remove](Wiki_Subcommand_remove.md) | Remove a data source from wiki.yml, its cache, and wiki.lock. | -| [Wiki_Subcommand_render](Wiki_Subcommand_render.md) | Update inline SPARQL result tables in markdown files. | -| [Wiki_Subcommand_serve](Wiki_Subcommand_serve.md) | Local HTTP server for live HTML preview and optional read-only SPARQL endpoint. | -| [Wiki_Subcommand_update](Wiki_Subcommand_update.md) | Check locked sources for newer commits and update wiki.lock. | -| [Wiki_Subcommand_upgrade](Wiki_Subcommand_upgrade.md) | Check PyPI for updates and upgrade wazootech-wiki. | - - - -Global flags: `-c`, `--wiki-inputs`. - -## Publishing - -- [Deploying to GitHub Pages](Deploying_to_GitHub_Pages.md) — CI workflow for this site -- [Obsidian Integration](Obsidian_Integration.md) — Shell Commands plugin workflows - -## Managing drift and schema evolution - -A common challenge in text-based memory bases is metadata drift—especially when files are updated programmatically by external LLM agents. The Wiki CLI provides two strategies to keep a compounding codebase clean over long periods: - -### Automated cleaning harness - -To prevent drift mechanically, you can wire a local Git hook or CI workflow that executes the following checks in order: - -1. **[Wiki Subcommand fmt](Wiki_Subcommand_fmt.md)**: Auto-formats Markdown structures and standardizes YAML frontmatter layout. -1. **[Wiki Subcommand lint](Wiki_Subcommand_lint.md) `--strict`**: Flags broken links, non-conforming filename patterns, and heading casing warnings as hard errors. -1. **[Wiki Subcommand check](Wiki_Subcommand_check.md) `--strict`**: Ensures frontmatter conforms to [SHACL](SHACL.md) shapes and bound JSON Schema documents (`wazoo:jsonSchema`). - -### Resilient schema evolution - -Enforcing schemas on text databases can become problematic as structures evolve. The Wiki CLI avoids schema rigidity using semantic web principles: - -- **Additive RDF properties**: Since frontmatter is compiled into a graph, new or unconstrained keys do not cause parsing failures. They are ingested as open-world triples that can be queried or ignored. -- **Decoupled validation**: SHACL and JSON Schema validation are diagnostic steps, not execution blockers. Files with invalid schemas can still be compiled, parsed, and queried. -- **Class-scoped shapes**: Shapes target specific classes (e.g., `sh:targetClass schema:TechArticle`). Introducing a new document type only requires writing a new shape constraint, leaving legacy documents untouched. -- **Namespace contexts**: Properties map to URIs via `graph.context` in [Wiki Configuration](Wiki_Configuration.md). You can rename or alias fields at the config layer without physically editing every source document. - -## Design - -The CLI follows a flat, scriptable surface and [Design Philosophies](Design_Philosophies.md) (silent success, composable stdout). For programmatic use from Python or TypeScript, see [Wiki Programmatic API](Wiki_Programmatic_API.md). - -## Pattern context - -This repository implements the [LLM Wiki](LLM_Wiki.md) pattern for [Personal Knowledge](Personal_Knowledge.md) wikis. Examples in the wild include [Farzapedia](Farzapedia.md) and coverage from Andrej Karpathy. - -Similar **agent memory filesystem** approaches include [Supermemory SMFS](Supermemory_SMFS.md), [Letta MemFS](Letta_MemFS.md), and [Agent Memory Filesystems](Agent_Memory_Filesystems.md). - -For a **standardized agent workspace** (typed graph, loop, blast-radius review), see [Vivary](Vivary.md). - -## Repository - -- Source and issues: [github.com/wazootech/wiki](https://github.com/wazootech/wiki) -- [Wiki CLI templates](#ecosystem-templates) — generic starter [wiki-template](https://github.com/wazootech/wiki-template); [LLM Wiki](LLM_Wiki.md) starter [llm-wiki-template](https://github.com/wazootech/llm-wiki-template) - -## Background - -- [Semantic Web](Semantic_Web.md) — RDF, Turtle, OWL, and related formats -- [Software Application Shape](Software_Application_Shape.md) — SHACL shape for `SoftwareApplication` pages (including this page) diff --git a/docs/wiki/Wiki_Configuration.md b/docs/wiki/Wiki_Configuration.md index 83990bf..40b1a94 100644 --- a/docs/wiki/Wiki_Configuration.md +++ b/docs/wiki/Wiki_Configuration.md @@ -280,7 +280,7 @@ The name is inferred from the URL (`solar-system`). To remove it: wiki remove solar-system ``` -See [Wiki Subcommand install](Wiki_Subcommand_install.md) and [Wiki Subcommand remove](Wiki_Subcommand_remove.md). +See [wiki install](wiki_install.md) and [wiki remove](wiki_remove.md). For the product framing behind recursive source composition, see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md). @@ -309,7 +309,7 @@ sparql_service: path: /api/sparql ``` -The endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint). +The endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [wiki serve](wiki_serve.md#sparql-endpoint). It is **opt-in by default** because enabling it exposes raw graph-query access in addition to HTML preview. @@ -336,7 +336,7 @@ fmt: # optional block — inline mapping (init writes) | `extensions` | optional (inline) | `[gfm, front_matters, wikilink, toc, footnote]` | writes | `wiki fmt` | | TOML path | optional | unset — see fallback chain below | omits (commented) | `wiki fmt` | -Omit `fmt` entirely to use fallbacks: `config_root/.mdformat.toml`, then upward search from each markdown file, then **Wiki CLI fmt defaults** (`wrap: "no"`, `end_of_line: lf`, extensions `gfm`, `front_matters`, `wikilink`, `toc`, `footnote`). See [Wiki Subcommand fmt](Wiki_Subcommand_fmt.md) for the full resolution order. +Omit `fmt` entirely to use fallbacks: `config_root/.mdformat.toml`, then upward search from each markdown file, then **Wiki CLI fmt defaults** (`wrap: "no"`, `end_of_line: lf`, extensions `gfm`, `front_matters`, `wikilink`, `toc`, `footnote`). See [wiki fmt](wiki_fmt.md) for the full resolution order. | Shape | Example | When to use | | -------------- | --------------------- | ------------------------------------------- | @@ -355,7 +355,7 @@ When `site.layout` is set, the CLI renders every page through that page layout ( The first-class presentation contract in this repository is layout files referenced from `site.layout` (for example `index.html`). -- The [Wiki CLI](Wiki_CLI.md) owns the semantic markdown-to-HTML pipeline and layout slot contract. +- The [wiki](wiki.md) owns the semantic markdown-to-HTML pipeline and layout slot contract. - Wiki page layout files are the primary built-in extension point for presentation. - Advanced themes or framework-specific sites such as Next.js, Mintlify, or other external docs stacks are treated as downstream integrations or separate layout/template repositories. @@ -501,7 +501,7 @@ Top-level **`fmt`** configures `wiki fmt` (mdformat). Two shapes are allowed — | Inline mapping | `fmt: { wrap: "no" }` | Default; what `wiki init` writes | | Relative path | `fmt: custom.toml` | Share one TOML file or keep fmt out of yaml | -Omit `fmt` entirely to use fallbacks: `config_root/.mdformat.toml`, then upward search from each markdown file, then **Wiki CLI fmt defaults** (`wrap: "no"`, `end_of_line: lf`, extensions `gfm`, `front_matters`, `wikilink`). See [Wiki Subcommand fmt](Wiki_Subcommand_fmt.md) for the full resolution order. +Omit `fmt` entirely to use fallbacks: `config_root/.mdformat.toml`, then upward search from each markdown file, then **Wiki CLI fmt defaults** (`wrap: "no"`, `end_of_line: lf`, extensions `gfm`, `front_matters`, `wikilink`). See [wiki fmt](wiki_fmt.md) for the full resolution order. Invalid inline keys or values fail when the config loads. Invalid TOML syntax fails when `wiki fmt` reads the file. @@ -545,12 +545,12 @@ Under `lint`, each rule is `error`, `warning`, or `off`: ## Related -- [Wiki CLI](Wiki_CLI.md#global-options) — `-c` and `--wiki-inputs` global options -- [Wiki Subcommand init](Wiki_Subcommand_init.md) — scaffold a new wiki project -- [Wiki Subcommand check](Wiki_Subcommand_check.md) — integrity checks -- [Wiki Subcommand lint](Wiki_Subcommand_lint.md) — convention audits -- [Wiki Subcommand query](Wiki_Subcommand_query.md) — ad-hoc SPARQL -- [Wiki Subcommand render](Wiki_Subcommand_render.md) — inline SPARQL tables -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint) — `#serve-api` config block +- [wiki](wiki.md#global-options) — `-c` and `--wiki-inputs` global options +- [wiki init](wiki_init.md) — scaffold a new wiki project +- [wiki check](wiki_check.md) — integrity checks +- [wiki lint](wiki_lint.md) — convention audits +- [wiki query](wiki_query.md) — ad-hoc SPARQL +- [wiki render](wiki_render.md) — inline SPARQL tables +- [wiki serve](wiki_serve.md#sparql-endpoint) — `#serve-api` config block - [Graph Cache](Graph_Cache.md) — `--cache` and graph reuse - [Style Guide](Style_Guide.md) — shapes and frontmatter diff --git a/docs/wiki/Wiki_Page_Layouts.md b/docs/wiki/Wiki_Page_Layouts.md index 72836cb..8427bac 100644 --- a/docs/wiki/Wiki_Page_Layouts.md +++ b/docs/wiki/Wiki_Page_Layouts.md @@ -56,8 +56,8 @@ Custom logos and favicons are layout markup plus `wiki.assets` overrides; see [C ## Related -- [Wiki Subcommand build](Wiki_Subcommand_build.md) +- [wiki build](wiki_build.md) -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md) +- [wiki serve](wiki_serve.md) - [Style Guide](Style_Guide.md) diff --git a/docs/wiki/Wiki_Programmatic_API.md b/docs/wiki/Wiki_Programmatic_API.md index e4c6f87..85117ec 100644 --- a/docs/wiki/Wiki_Programmatic_API.md +++ b/docs/wiki/Wiki_Programmatic_API.md @@ -207,10 +207,10 @@ Page layouts substitute `%wiki.*%` slots. `build_layout_context` validates a typ ## CLI parity -Library operations mirror subcommands documented under [Wiki CLI](Wiki_CLI.md). The CLI adds silence-on-success, `--strict`, pipe formats, and exit codes. For agent workflows that shell out, prefer `skills/wiki/scripts/audit.sh`; for in-process CI, prefer `Wiki` and typed reports. +Library operations mirror subcommands documented under [wiki](wiki.md). The CLI adds silence-on-success, `--strict`, pipe formats, and exit codes. For agent workflows that shell out, prefer `skills/wiki/scripts/audit.sh`; for in-process CI, prefer `Wiki` and typed reports. ## Related -- [Wiki CLI](Wiki_CLI.md) — command reference +- [wiki](wiki.md) — command reference - [Wiki Configuration](Wiki_Configuration.md) — config semantics - [Design Philosophies](Design_Philosophies.md) — silent success, composable stdout diff --git a/docs/wiki/Wiki_Skills.md b/docs/wiki/Wiki_Skills.md index d2de952..7458341 100644 --- a/docs/wiki/Wiki_Skills.md +++ b/docs/wiki/Wiki_Skills.md @@ -78,7 +78,7 @@ See `skills/wiki/references/install.md`. Non-interactive `wiki init` for wiki project structure (config, starter pages), then a short **tweak** step: replace the starter first page, and optionally uncomment blocks in `wiki.yml`. Requires **`wiki` on PATH** before any init or file edits. Default post-init `wiki check --strict` with opt-out. -See `skills/wiki/references/init.md` and [Wiki Subcommand init](Wiki_Subcommand_init.md). +See `skills/wiki/references/init.md` and [wiki init](wiki_init.md). ## Improve workflow @@ -122,4 +122,4 @@ Human-oriented install and daily workflow: [Getting Started](Getting_Started.md) - [LLM Wiki](LLM_Wiki.md) - [Procedural Knowledge](Procedural_Knowledge.md) -- [Wiki CLI](Wiki_CLI.md) +- [wiki](wiki.md) diff --git a/docs/wiki/Wiki_Subcommand_build.md b/docs/wiki/Wiki_Subcommand_build.md index a09422c..8c9f343 100644 --- a/docs/wiki/Wiki_Subcommand_build.md +++ b/docs/wiki/Wiki_Subcommand_build.md @@ -1,68 +1,7 @@ --- type: TechArticle -headline: wiki build -description: Generate a static HTML site from the wiki. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_build --- - -# `wiki build` - -Compile markdown and data files into static HTML with wikilinks, backlinks, table of contents, and typed templates/infoboxes. Pages with frontmatter embed all metadata format views so the chip picker works without JavaScript. - -## Usage - -```bash -wiki build -wiki build --output-dir _site --site-base-url /wiki -v -wiki build --site-url-style file -wiki build --site-base-url '' -wiki build --render --reload -wiki build --render --cache -wiki build --no-check -``` - -## Options - -| Flag | Default | Description | -| ------------------ | ----------- | ----------------------------------------------------------------------- | -| `--output-dir` | `_site` | Site root on disk | -| `--site-base-url` | from config | Override `site.base_url` (`/wiki`, `/my-wiki`, or `''`) | -| `--site-url-style` | from config | Override `site.url_style`: `dir` or `file` | -| `--render` | off | Run [Wiki Subcommand render](Wiki_Subcommand_render.md) before building | -| `--reload` | off | Rebuild graph when using `--render` | -| `--cache` | off | Persist a warm graph under `.wiki/cache/` when using `--render` | -| `--no-check` | off | Skip pre-build `lint` then `check` preflight | -| `-v`, `--verbose` | off | List output paths | - -## Output layout - -With `site.base_url: /wiki` and `site.url_style: dir`: - -``` -_site/wiki/Alice/index.html → /wiki/Alice/ -``` - -Assets from `wiki.assets` copy under the same prefix. See [Wiki Configuration](Wiki_Configuration.md). - -## Metadata view - -Each built page embeds compacted JSON-LD plus Turtle, N3, RDF/XML, N-Triples, TriG, and N-Quads. JSON-LD is selected by default; the chip row stays usable without JavaScript. - -## Wiki page layout - -If your [Wiki Configuration](Wiki_Configuration.md#page-layout) sets `site.layout`, every page is rendered through that page layout unless `wazoo:layout` overrides it. The builder substitutes layout slots (see [Layout slots](Wiki_Configuration.md#layout-slots)). - -If the configured page layout file is missing, the packaged `index.html` fallback is used silently. - -## Checks and collisions - -By default, convention (`wiki lint`) then integrity (`wiki check`) preflight must pass before the output directory is wiped and rebuilt. Output path collisions abort the build with errors. - -Wiki page bodies are rendered without raw HTML passthrough; inline HTML tags in markdown are not emitted as live markup in built pages. - -`--output-dir` must point at a disposable directory that does not overlap the wiki config root, input directories, asset directories, or the page layout folder. The build refuses to delete paths that would remove source or config files. - -## Related - -- [Deploying to GitHub Pages](Deploying_to_GitHub_Pages.md) -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md) -- [Wiki Configuration](Wiki_Configuration.md#page-layout) diff --git a/docs/wiki/Wiki_Subcommand_check.md b/docs/wiki/Wiki_Subcommand_check.md index 4bbdc67..0938e15 100644 --- a/docs/wiki/Wiki_Subcommand_check.md +++ b/docs/wiki/Wiki_Subcommand_check.md @@ -1,83 +1,7 @@ --- type: TechArticle -headline: wiki check -description: Integrity checks — SHACL validation, JSON Schema frontmatter, route safety, and layout frontmatter. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_check --- - -# `wiki check` - -Run **integrity** checks on the wiki: strict **SHACL** validation, **JSON Schema** frontmatter validation, route safety, output collisions, and layout frontmatter contracts. - -Exits **0 silently** on success unless `-v` is set. See [Design Philosophies](Design_Philosophies.md). - -## Usage - -```bash -wiki check -wiki check wiki/Some_Page.md -wiki check wiki/A.md wiki/B.md -wiki check -v -wiki check --strict -``` - -## Options - -| Flag | Description | -| ----------------- | ------------------------------------------------------------------------------------- | -| `FILE...` | Optional documents; otherwise entire wiki (scoped mode: SHACL + JSON Schema per file) | -| `-v`, `--verbose` | Print warnings | -| `--strict` | Treat warnings as errors (exit 1) | - -## What is checked - -### Full wiki (default) - -`wiki check` with no `FILE` argument runs every check below. - -### Always errors (not configurable) - -- **SHACL** — shapes from wiki frontmatter (`sh:NodeShape`, etc.) on the full RDF graph -- **Route safety** — unsafe path segments (spaces, reserved characters, and similar) -- **Output collisions** — two wiki sources mapping to the same built URL (against default `_site` layout) - -### Configurable (`check.*` in `wiki.yaml`) - -| Rule key | What it audits | -| --------------------- | ------------------------------------------------------------------- | -| `missing_layout_file` | `wazoo:layout` paths that do not resolve to a readable `.html` file | -| `frontmatter_schema` | Frontmatter that fails JSON Schema validation | -| `missing_schema_ref` | `wazoo:jsonSchema` paths or URLs that cannot be loaded | -| `remote_schema_refs` | Policy for remote schema URLs: `allow`, `deny`, or `allowlist` | -| `remote_schema_hosts` | Hostnames allowed when `remote_schema_refs` is `allowlist` | - -Default: `missing_layout_file`, `frontmatter_schema`, and `missing_schema_ref` are `error`. `remote_schema_refs` defaults to `allow`. - -### JSON Schema frontmatter - -Bind schemas on `sh:NodeShape` documents with `wazoo:jsonSchema` and `sh:targetClass`. Type-level schemas apply to every matching page; pages may append extra schemas with their own `wazoo:jsonSchema` (string or list). Local refs resolve under the wiki config root; remote `http(s)` URLs are fetched at check time unless `check.remote_schema_refs` is `deny` or the host is outside `check.remote_schema_hosts` when using `allowlist`. Shape binding documents are excluded from instance validation. See [SHACL](SHACL.md) and [Style Guide](Style_Guide.md#shacl-shapes). - -Broken links, filename pattern, and heading style are **not** part of `wiki check` — use [Wiki Subcommand lint](Wiki_Subcommand_lint.md). - -### Scoped mode (one or more FILE args) - -`wiki check path/to/Page.md` (or multiple paths) runs **SHACL and JSON Schema** per file. Route safety, output collisions, and layout frontmatter rules are **full-wiki only**. Cross-document SHACL interactions may only appear in a full-wiki check. Broken links on those pages require `wiki lint` with the same paths. - -`--strict` applies only when warnings exist; scoped mode does not emit warnings today. - -### Related CI commands - -| Command | Purpose | -| --------------------- | ---------------------------------------------------- | -| `wiki lint --strict` | Broken links, filename pattern, headings, link style | -| `wiki fmt --check` | mdformat consistency | -| `wiki render --check` | Stale inline SPARQL result blocks | -| `wiki link --check` | Remaining missing-wikilink opportunities | - -`wiki build` runs `wiki lint` then `wiki check` before writing output unless `--no-check`. - -## Related - -- [Wiki Configuration](Wiki_Configuration.md) — `check.*` severities -- [SHACL](SHACL.md) — shape and JSON Schema binding -- [Wiki Subcommand lint](Wiki_Subcommand_lint.md) — convention lane -- [Style Guide](Style_Guide.md) diff --git a/docs/wiki/Wiki_Subcommand_export.md b/docs/wiki/Wiki_Subcommand_export.md index 0891b8e..9d4a636 100644 --- a/docs/wiki/Wiki_Subcommand_export.md +++ b/docs/wiki/Wiki_Subcommand_export.md @@ -1,50 +1,7 @@ --- type: TechArticle -headline: wiki export -description: Export document frontmatter as RDF or JSON-LD. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_export --- - -# `wiki export` - -Serialize parsed **frontmatter** (and RDF derived from it) for one file or the whole wiki. - -## Usage - -```bash -wiki export -wiki export wiki/Page.md -wiki export wiki/A.md wiki/B.md -wiki export wiki/Page.md -f turtle -wiki export -f json-ld -o wiki.json -wiki export wiki/Page.md --mode compacted -f json-ld -``` - -## Options - -| Flag | Default | Description | -| ---------------- | ------------- | ---------------------------------------------------------------- | -| `FILE...` | all wiki docs | One or more wiki documents, or omit for entire wiki | -| `-f`, `--format` | `dict` | `dict`, `json-ld`, `turtle`, `xml`, `n3`, `nt`, `trig`, `nquads` | -| `--mode` | `expanded` | `expanded` or `compacted` serialization mode | -| `-o`, `--output` | stdout | Output file | - -## Output shape - -For `dict` and `json-ld`, each entry is `{"name": "", "rdf": ...}`. - -Raw RDF formats (`turtle`, etc.) on a **single** FILE write plain serialization without a JSON wrapper. Multiple FILE args or whole-wiki export with raw formats is not supported — use `dict` or `json-ld`, or export one file at a time. - -`--mode compacted` is most visible for JSON-LD, where it emits `@context` and compacted terms when the wiki context provides them. - -## Related - -- [RDF](RDF.md) -- [RDF XML](RDF_XML.md) -- [Turtle](Turtle.md) -- [JSON LD](JSON_LD.md) -- [Notation3](Notation3.md) -- [N Triples](N_Triples.md) -- [TriG](TriG.md) -- [N Quads](N_Quads.md) -- [XML](XML.md) -- [Style Guide](Style_Guide.md) diff --git a/docs/wiki/Wiki_Subcommand_fmt.md b/docs/wiki/Wiki_Subcommand_fmt.md index 98c5a3e..60fdab4 100644 --- a/docs/wiki/Wiki_Subcommand_fmt.md +++ b/docs/wiki/Wiki_Subcommand_fmt.md @@ -1,86 +1,7 @@ --- type: TechArticle -headline: wiki fmt -description: Format markdown wiki pages using mdformat with wikilink preservation. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_fmt --- - -# `wiki fmt` - -Format markdown wiki pages in-place using **mdformat**. Mechanical markdown style (ATX headings, list spacing, GFM tables, frontmatter layout) is configured under the top-level **`fmt`** key in `wiki.yaml` (or `wiki.json`). - -## Configuration - -### Inline `fmt` (default) - -`wiki init` scaffolds inline `fmt` in `wiki.yaml`: - -```yaml -fmt: - wrap: "no" - end_of_line: lf - extensions: [gfm, front_matters, wikilink, toc, footnote] -``` - -Keys and values follow [mdformat configuration](https://mdformat.readthedocs.io/en/stable/users/configuration_file.html). Unknown keys fail at config load; invalid values fail at load or when `wiki fmt` reads TOML. - -An empty mapping (`fmt: {}`) is valid and resolves to the same **Wiki CLI fmt defaults** as omitting `fmt` when no TOML file applies (`wrap: "no"`, `end_of_line: lf`, extensions `gfm`, `front_matters`, `wikilink`, `toc`, `footnote`). - -### Pointer mode (optional TOML file) - -Instead of an inline mapping, set `fmt` to a **relative path** from the config file directory: - -```yaml -fmt: .mdformat.toml -``` - -Create the file beside `wiki.yaml` with the same keys as inline `fmt` (for example `wrap = "no"`, `end_of_line = "lf"`, `extensions = ["gfm", "frontmatter", "wikilink", "toc", "footnote"]`). Absolute paths are rejected at config load. - -### Resolution order - -`wiki fmt` stops at the **first** source below. Inline `fmt` always wins — it never merges with a `.mdformat.toml` on disk. - -1. **Inline** — `fmt:` mapping in `wiki.yaml` (`fmt: {}` counts as inline and uses Wiki CLI defaults) -1. **Pointer** — TOML at the relative path in `fmt:` -1. **Wiki TOML** — `config_root/.mdformat.toml` when `fmt` is omitted or the pointer file is missing -1. **Parent walk** — nearest `.mdformat.toml` above the markdown file (mdformat behavior) -1. **Defaults** — Wiki CLI fmt defaults (`wrap: "no"`, `end_of_line: lf`, `gfm` / `front_matters` / `wikilink` / `toc` / `footnote`) - -`wiki fmt -v` prints which step matched (for example `Using inline fmt in wiki config.`). - -| Concern | Command | Config | -| --------------------- | ------------- | ------------------------------------------------ | -| Mechanical markdown | `wiki fmt` | `fmt:` in `wiki.yaml` (inline or path) | -| Editorial conventions | `wiki lint` | `wiki.yaml` → `lint:` | -| Link integrity | `wiki lint` | `wiki.yaml` → `lint:` | -| Dynamic SPARQL tables | `wiki render` | (query-driven; blocks are left untouched by fmt) | - -Recommended CI order: `fmt --check` → `lint --strict` → `check --strict` → `render --check`. - -## Usage - -```bash -wiki fmt -wiki fmt wiki/Some_Page.md -wiki fmt --check -wiki fmt -v -``` - -From another directory, pass the config path on the main command: - -```bash -wiki --config docs fmt -v -``` - -## Options - -| Flag | Description | -| ----------------- | ------------------------------------------------------------------------- | -| `FILE...` | Optional markdown paths; otherwise entire wiki | -| `--check` | Check formatting without modifying files; exits 1 if formatting is needed | -| `-v`, `--verbose` | Print fmt config source and formatted files | - -## Related - -- [Style Guide.md](Style_Guide.md) -- [Wiki CLI.md](Wiki_CLI.md) -- [Wiki Configuration.md](Wiki_Configuration.md) diff --git a/docs/wiki/Wiki_Subcommand_graph.md b/docs/wiki/Wiki_Subcommand_graph.md index 5bebd52..1c37f4b 100644 --- a/docs/wiki/Wiki_Subcommand_graph.md +++ b/docs/wiki/Wiki_Subcommand_graph.md @@ -1,57 +1,7 @@ --- type: TechArticle -headline: wiki graph -description: List read-only RDF named graphs for root and installed source provenance. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_graph --- - -# `wiki graph` - -Inspect read-only RDF named graph boundaries for a composed Wiki. - -## Usage - -```bash -wiki graph list -``` - -`wiki graph list` prints the root graph plus one graph for each installed source available from `wiki.lock` and the local `.wiki/sources/` cache. - -| Column | Meaning | -| ------------- | --------------------------------------------- | -| `name` | `root` or the source name | -| `kind` | `root` or `source` | -| `uri` | Named graph URI for SPARQL `GRAPH` clauses | -| `commit` | Short resolved commit for installed sources | -| `required_by` | Source dependency owners, or `root` if direct | - -## Query a source graph - -Use the listed URI with native SPARQL: - -```sparql -SELECT ?s ?name WHERE { - GRAPH { - ?s schema:name ?name . - } -} -``` - -Use `GRAPH ?g` to include provenance in results: - -```sparql -SELECT ?g ?s WHERE { - GRAPH ?g { - ?s a schema:Thing . - } -} -``` - -## Read-only boundary - -`wiki graph list` is discovery only. It does not install, update, remove, edit, or write back to source repositories. Writable source workflows and SPARQL Update are intentionally deferred. - -## Related - -- [Wiki Subcommand query](Wiki_Subcommand_query.md) -- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) -- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) diff --git a/docs/wiki/Wiki_Subcommand_init.md b/docs/wiki/Wiki_Subcommand_init.md index eac1e5c..23140e5 100644 --- a/docs/wiki/Wiki_Subcommand_init.md +++ b/docs/wiki/Wiki_Subcommand_init.md @@ -1,83 +1,7 @@ --- type: TechArticle -headline: wiki init -description: Scaffold wiki.yml and starter wiki pages interactively. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_init --- - -# `wiki init` - -Create a new wiki project in the **current directory**: `wiki.yml`, `README.md`, and starter files under `wiki/`. - -Does not use loaded Config; safe to run before a config exists. Init runs once per clean directory — if `wiki.yml`, `README.md`, or a non-empty `wiki/` already exist, use a new directory or remove those files before re-running. - -## Usage - -```bash -wiki init -wiki init --git -wiki init --repo wazootech/wiki -wiki init --graph-context-wiki https://example.org/mywiki/ --site-base-url /mywiki -``` - -## Config vs scaffold - -**Config flags** write keys into `wiki.yml` via the packaged template ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)). - -**Scaffold-only** effects copy files (`README.md`, `wiki/*.md`) or run `git init`. - -## Options - -| Flag | Description | `wiki.yml` key | -| -------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| `--git` | Run `git init` after scaffolding | — | -| `--repo` | GitHub `owner/repo`; infer `graph.context.wiki` and `site.base_url` for GitHub Pages | `graph.context.wiki`, `site.base_url` (inferred) | -| `--graph-context-wiki` | Override `graph.context.wiki` (overrides `--repo` inference) | `graph.context.wiki` | -| `--site-base-url` | Override `site.base_url` (default `/wiki` or inferred from `--repo`) | `site.base_url` | -| `--site-url-style` | Override `site.url_style`: `dir` or `file` (default `dir`) | `site.url_style` | -| `--graph-content-predicate` | Override `graph.content_predicate` CURIE (e.g. `schema:articleBody`) | `graph.content_predicate` | -| `--link-style` | Override `link.style`: standard page links (`standard`) or wikilinks (`wikilink`) | `link.style` | -| `--wiki-inputs` | Override `wiki.inputs` list (can be specified multiple times, default `[wiki]`) | `wiki.inputs` | -| `--graph-base-iri` | Override `graph.base_iri` URI | `graph.base_iri` | -| `--graph-implicit-types` | Override `graph.implicit_types` (can be specified multiple times) | `graph.implicit_types` | -| `--graph-implicit-types-policy` | Override `graph.implicit_types_policy`: `fallback` or `append` | `graph.implicit_types_policy` | -| `--graph-include-file-extension` | Override `graph.include_file_extension` flag (defaults to `--no-graph-include-file-extension`) | `graph.include_file_extension` | - -## URL resolution - -When `--graph-context-wiki` is not passed, init resolves `graph.context.wiki` in this order: - -1. **`--repo`** — GitHub Pages project site: `https://{owner}.github.io/{repo}/` and `site.base_url: /{repo}` (accepts `owner/repo`, HTTPS, or SSH URLs). -1. **Git remote** — If `.git` already exists or `--git` was passed, parse `git remote get-url origin` when it points at GitHub. -1. **Interactive prompt** — **Custom wiki namespace IRI** (default `https://wiki.example.org/`). - -`--graph-context-wiki` always wins over `--repo` and remote detection. `--site-base-url` overrides the inferred path from `--repo`. - -Document subject IRIs default to `graph.context.wiki`. Set optional `graph.base_iri` in `wiki.yml` when auto-generated document IRIs must differ from the `wiki:` namespace (see [Wiki Configuration](Wiki_Configuration.md)). - -## Prompts - -When no flag or git remote supplies `graph.context.wiki`, init prompts once: - -1. **Custom wiki namespace IRI** (default `https://wiki.example.org/`) → `wiki:` in `graph.context` - -When the namespace came from that prompt, the prompt ends and initialization proceeds. - -Always includes `schema`, `wiki`, `wazoo`, `foaf`, `dc`, `dcterms`, `sh`, and `xsd` prefixes. The `wazoo` URI is fixed in the scaffold (`https://schema.wazoo.dev/`), like the other built-in prefixes. - -## Generated config - -New wiki projects receive a plain `wiki.yml` rendered from [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml). Jinja variables (such as `graph_context_wiki`, `site_base_url`, `graph_content_predicate`, and `link_style`) map from init CLI flags into nested blocks. - -For every key — schema default, whether init writes it, and which command audits it — see [Wiki Configuration → Overview](Wiki_Configuration.md#overview) and the per-block defaults tables in [Wiki Configuration](Wiki_Configuration.md). - -## Generated files - -- `README.md` — starter wiki overview and common commands -- `wiki/Person_Shape.md` — starter `sh:NodeShape` for `schema:Person` -- `wiki/Ethan_Davidson.md` — starter `schema:Person` example (includes a tweak comment to replace with your first page) - -## Related - -- [Getting Started](Getting_Started.md) -- [Wiki Configuration](Wiki_Configuration.md) -- [Wiki Page Layouts](Wiki_Page_Layouts.md) diff --git a/docs/wiki/Wiki_Subcommand_install.md b/docs/wiki/Wiki_Subcommand_install.md index 073a2c8..6990146 100644 --- a/docs/wiki/Wiki_Subcommand_install.md +++ b/docs/wiki/Wiki_Subcommand_install.md @@ -1,45 +1,7 @@ --- type: TechArticle -headline: wiki install -description: Fetch and lock external data sources declared in wiki.yml. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_install --- - -# `wiki install` - -Fetch external data sources (git repositories with wiki pages or RDF data), resolve commit SHAs, and pin them in `wiki.lock`. Without arguments, installs all sources declared in the `sources:` block of `wiki.yml`. With a URL, adds the source to `wiki.yml` first, then fetches and locks it. - -You can use GitHub `owner/repo` shorthand instead of a full URL — `EthanThatOneKid/solar-system-wiki` expands to `https://github.com/EthanThatOneKid/solar-system-wiki.git` automatically. - -**Transitive dependencies** are resolved recursively. `wiki install` reads each cloned source's own `wiki.yml` to discover its `sources:` block, fetches those transitive sources, and locks them too — forming a dependency tree. Circular dependency chains are detected and raise an error. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error. - -## Usage - -```bash -wiki install -wiki install https://github.com/EthanThatOneKid/solar-system-wiki.git -wiki install https://github.com/EthanThatOneKid/solar-system-wiki.git#v0.1.0 -wiki install EthanThatOneKid/solar-system-wiki -``` - -## Options - -| Flag | Description | -| ----- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `URL` | Git repository URL to add and install. Supports `#ref` pinning (branch, tag, or commit). If omitted, installs all sources from `wiki.yml`. | - -## Lockfile - -`wiki install` produces `wiki.lock` in the same directory as `wiki.yml`. This machine-authored JSON file records the resolved commit SHA, requested ref, and fetch timestamp for each source. Check it into version control so builds are reproducible — the lockfile is the source of truth for which version of each source is used. - -## Source cache - -Cloned repositories are cached under `.wiki/sources//repo/` relative to the wiki config root. `wiki install` always fetches the latest remote refs (shallow clone, `--depth 1`) so it stays fast. - -## `.gitignore` - -The `.wiki/` source cache directory (and the `_site/` build output) should not be committed to version control. `wiki init` scaffolds a `.gitignore` that includes both directories. - -## Related - -- [Wiki Subcommand remove](Wiki_Subcommand_remove.md) -- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) diff --git a/docs/wiki/Wiki_Subcommand_link.md b/docs/wiki/Wiki_Subcommand_link.md index 680a109..d2bfeea 100644 --- a/docs/wiki/Wiki_Subcommand_link.md +++ b/docs/wiki/Wiki_Subcommand_link.md @@ -1,65 +1,7 @@ --- type: TechArticle -headline: wiki link -description: Suggest missing wikilinks and repair unambiguous broken internal links. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_link --- - -# `wiki link` - -Suggest **missing wikilinks** for plain-text mentions of other wiki pages, or **repair** broken internal links when the fix is unambiguous. Report-only by default — mutations require explicit flags. - -## Usage - -```bash -wiki link -wiki link wiki/Some_Page.md -wiki link wiki/A.md wiki/B.md -wiki link -v -wiki link --check -wiki link --dry-run --apply -wiki link --apply -wiki link --fix-broken -wiki link --fix-broken --dry-run -``` - -## Options - -| Flag | Description | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `FILE...` | Optional markdown paths; otherwise entire wiki | -| `--apply` | Insert internal links for each suggestion (body only, never frontmatter); format from `link.style` in [wiki.yaml](Wiki_Configuration.md) (`standard` or `wikilink`) | -| `--fix-broken` | Repair unambiguous broken wikilinks and internal markdown page links | -| `-n`, `--dry-run` | Preview `--apply` or `--fix-broken` without writing files | -| `-c`, `--check` | Exit 1 if opportunities or broken links remain (CI gate) | -| `-v`, `--verbose` | Include target titles in report output; print changed files when applying | - -## Detection rules - -Missing-link suggestions skip: - -- Existing wikilinks and markdown links -- Fenced and inline code -- Self-links and overlapping aliases (longest alias wins) -- Short single-word acronyms (for example `HTML`, `JSON`) unless the page slug humanizes to the same text - -Broken-link repair (`--fix-broken`) only runs when: - -- The target page rename is listed in `link.renames` (see [Wiki Configuration](Wiki_Configuration.md)) -- A unique fuzzy route match exists among wiki pages -- A unique fuzzy heading fragment exists on the target page - -It never auto-creates pages or deletes links. Asset links, metadata CURIEs, and ambiguous matches stay manual. - -## Why not check or lint? - -- **`wiki lint`** is the convention lane — broken links, filename pattern, heading style, and link style. It reports but does not edit files; repair is `wiki link --fix-broken`. Missing wikilinks are optional enrichment, not a lint violation. -- **`wiki check`** is the integrity lane — SHACL, JSON Schema frontmatter, routes, collisions, layout frontmatter. It does not scan prose for broken links. -- **`wiki link`** requires explicit `--apply` or `--fix-broken` because suggestions are heuristic and repairs are conservative by design. -- See [Design Philosophies](Design_Philosophies.md#check-lint-fmt-and-link) for the full lane model. - -## Related - -- [Wiki Subcommand lint](Wiki_Subcommand_lint.md) — convention lane (`lint.broken_links`) -- [Wiki Subcommand check](Wiki_Subcommand_check.md) — integrity lane (SHACL, JSON Schema, routes, layout) -- [Style Guide](Style_Guide.md) — internal link conventions -- [Wiki CLI](Wiki_CLI.md) diff --git a/docs/wiki/Wiki_Subcommand_lint.md b/docs/wiki/Wiki_Subcommand_lint.md index cab0366..03ce7df 100644 --- a/docs/wiki/Wiki_Subcommand_lint.md +++ b/docs/wiki/Wiki_Subcommand_lint.md @@ -1,72 +1,7 @@ --- type: TechArticle -headline: wiki lint -description: Convention audits for broken links, filename patterns, heading style, and internal link style. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_lint --- - -# `wiki lint` - -Run **convention** audits on the wiki: broken links, filename pattern, heading style, and internal link style. - -Exits **0 silently** on success unless `-v` is set. See [Design Philosophies](Design_Philosophies.md). - -## Usage - -```bash -wiki lint -wiki lint wiki/Some_Page.md -wiki lint wiki/A.md wiki/B.md -wiki lint -v -wiki lint --strict -``` - -## Options - -| Flag | Description | -| ----------------- | ---------------------------------------------- | -| `FILE...` | Optional markdown paths; otherwise entire wiki | -| `-v`, `--verbose` | Print warnings | -| `--strict` | Treat warnings as errors (exit 1) | - -## What is linted - -### Configurable (`lint.*` in `wiki.yaml`) - -| Rule key | What it audits | -| -------------------- | ------------------------------------------------------------------------------------------------ | -| `broken_links` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs | -| `filename_pattern` | Full filename vs `wiki.filename_pattern` regex (`.md` files only) | -| `headings` | Sentence-case H2+ (H1 title case conventional), numbered headings (ATX syntax is **`wiki fmt`**) | -| `heading_levels` | Heading depth must increase by one level at a time (MD001-inspired) | -| `duplicate_headings` | Duplicate H2+ heading text in the same document (MD024-inspired) | -| `thematic_breaks` | Horizontal rules (`---`, `***`, `___`) in body prose | -| `link_style` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` | - -Each rule is `error`, `warning`, or `off`. Defaults: `broken_links`, `filename_pattern`, and `link_style` are `warning`; `headings`, `heading_levels`, `duplicate_headings`, and `thematic_breaks` are `off`. - -`wiki lint` reports broken links only — it does not repair them. Use [Wiki Subcommand link](Wiki_Subcommand_link.md) `--fix-broken` for unambiguous repairs (rename map, unique fuzzy slug, or heading match). - -Route safety errors (spaces, unsafe URL characters) abort lint with errors before convention rules run. - -### Single-file mode - -`wiki lint path/to/Page.md` runs broken-link, filename, heading, and link-style audits for that route only. - -## Related CI commands - -| Command | Purpose | -| --------------------- | ---------------------------------------------------------------- | -| `wiki fmt --check` | mdformat consistency (`fmt:` in wiki config or fallback TOML) | -| `wiki lint --strict` | Conventions (`lint:` in yaml) | -| `wiki check --strict` | SHACL, JSON Schema frontmatter, route safety, layout frontmatter | -| `wiki render --check` | Stale inline SPARQL result blocks | - -Run in that order in CI: `fmt`, then `lint`, then `check` — so mechanical fixes land before conventions and integrity checks. - -`wiki build` runs `wiki lint` then `wiki check` before writing output unless `--no-check`. - -## Related - -- [Wiki Configuration](Wiki_Configuration.md) — `lint.*` severities and config semantics -- [Wiki Subcommand check](Wiki_Subcommand_check.md) — integrity lane -- [Style Guide](Style_Guide.md) diff --git a/docs/wiki/Wiki_Subcommand_mcp.md b/docs/wiki/Wiki_Subcommand_mcp.md index a9d0c14..acde490 100644 --- a/docs/wiki/Wiki_Subcommand_mcp.md +++ b/docs/wiki/Wiki_Subcommand_mcp.md @@ -1,145 +1,7 @@ --- type: TechArticle -headline: wiki mcp -description: Run a read-only MCP server for querying the wiki graph. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_mcp --- - -# `wiki mcp` - -Start a local [Model Context Protocol](https://modelcontextprotocol.io/) server for the configured Wiki graph. The server is read-only and query-first: it exposes SPARQL execution and graph context for agents, not page editing, formatting, link repair, build, or filesystem automation. - -## Usage - -```bash -wiki mcp -wiki -c docs/wiki.yml mcp -wiki --wiki-inputs docs/wiki mcp -wiki mcp --mode stdio -wiki mcp --cache -``` - -`stdio` is the default and only transport in the first version. - -## Claude Code setup - -Register the local server with Claude Code: - -```bash -claude mcp add wiki -- wiki -c docs/wiki.yml mcp -``` - -Generic stdio MCP clients should run the same command shape: - -```bash -wiki -c docs/wiki.yml mcp -``` - -## Options - -| Flag | Default | Description | -| --------- | ------- | ------------------------------------------------------------ | -| `--mode` | `stdio` | MCP transport mode. | -| `--cache` | off | Persist graph artifacts under `.wiki/cache` across launches. | - -## Tools - -### `query_sparql` - -Execute SPARQL against the compiled wiki graph. - -Parameters: - -```json -{ - "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10", - "format": "json", - "inference": true, - "reload": false -} -``` - -Allowed query forms: `SELECT`, `ASK`, `CONSTRUCT`, and `DESCRIBE`. SPARQL Update and unsupported query forms are rejected before execution. - -`format` reuses [Wiki Subcommand query](Wiki_Subcommand_query.md) names and aliases: `table`, `json`, `csv`, `tsv`, `turtle`, `n3`, and `markdown`. The MCP default is `json`. - -The tool returns a structured object: - -```json -{ - "format": "json", - "query_form": "SELECT", - "result": "..." -} -``` - -### `describe_wiki` - -Return factual context for writing grounded SPARQL: - -- Wiki CLI version -- Config path and inputs -- Namespace bindings from the built graph -- Graph stats for the default inferred graph -- Observed vocabulary from the graph - -The vocabulary summary is intentionally load-bearing for agent use. It lists real classes and predicates so agents can avoid inventing predicates, getting empty results, and treating a bad query as missing data. - -Example shape: - -```json -{ - "version": "0.1.21", - "config": "docs/wiki.yml", - "inputs": ["docs/wiki"], - "namespaces": { - "schema": "https://schema.org/", - "wiki": "https://wiki.example.org/" - }, - "graph": { - "triples": 1234, - "subjects": 120, - "predicates": 45, - "objects": 900, - "inference": true - }, - "vocabulary": { - "classes": [ - { "iri": "https://schema.org/Person", "curie": "schema:Person", "count": 12 } - ], - "predicates": [ - { "iri": "https://schema.org/name", "curie": "schema:name", "count": 42 } - ] - } -} -``` - -Vocabulary limits are intentionally compact: top 25 classes by `rdf:type` usage and top 50 predicates by triple count. - -## Resources - -| Resource | MIME type | Purpose | -| ------------------- | ------------------ | -------------------------------------------------------------- | -| `wiki://info` | `application/json` | Version, config, inputs, graph settings, stats, and vocabulary | -| `wiki://namespaces` | `application/json` | Prefix map for SPARQL authoring | -| `wiki://graph.ttl` | `text/turtle` | Current inferred graph serialized as Turtle | - -## Safety model - -`wiki mcp` is read-only by default: - -- No wiki source mutation -- No build output writes -- No formatting changes -- No link repair -- No generic file read/write tools -- No Obsidian automation -- No SPARQL Update - -The command reuses the same graph cache behavior as other Wiki CLI operations: in-process caching is always used within one running MCP server, and `--cache` enables filesystem persistence under `.wiki/cache` for faster reuse across MCP launches. `reload=true` on `query_sparql` rebuilds the in-memory graph before executing the query; with `--cache`, the rebuilt graph is also written back to the filesystem cache. - -## Related - -- [Wiki Subcommand query](Wiki_Subcommand_query.md) -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint) -- [Graph Cache](Graph_Cache.md) -- [SPARQL](SPARQL.md) diff --git a/docs/wiki/Wiki_Subcommand_query.md b/docs/wiki/Wiki_Subcommand_query.md index 87f146c..2cb650f 100644 --- a/docs/wiki/Wiki_Subcommand_query.md +++ b/docs/wiki/Wiki_Subcommand_query.md @@ -1,89 +1,7 @@ --- type: TechArticle -headline: wiki query -description: Run SPARQL SELECT or CONSTRUCT against the wiki graph. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_query --- - -# `wiki query` - -Execute **SPARQL** against the loaded wiki graph (with OWL-RL inference unless `--no-inference`). Unscoped queries read the union of root content and installed sources. Use native SPARQL `GRAPH` clauses when you need source boundaries. - -## Usage - -```bash -wiki query "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" -wiki query --pretty "SELECT ?given ?family WHERE { ?s schema:givenName ?given ; schema:familyName ?family }" -cat query.sparql | wiki query -f json -wiki query "SELECT ?given WHERE { ?s schema:givenName ?given }" --jq 'results.bindings[].given.value' -wiki query "..." --reload -v -wiki query "..." --cache -``` - -## Options - -| Flag | Description | -| ----------------- | ------------------------------------------------------------------------------ | -| `QUERY` | SPARQL string, or omit to read stdin | -| `-f`, `--format` | `table` (default), `json`, `csv`, `tsv`, `turtle`, `n3`, `markdown` | -| `-o`, `--output` | Write results to a file | -| `--pretty` | Rich table for SELECT results (stdout only; incompatible with `-o` and `--jq`) | -| `--no-inference` | Skip OWL-RL | -| `--reload` | Rebuild in-memory graph in this process | -| `--cache` | Persist a warm graph under `.wiki/cache/` for reuse across new processes | -| `--jq` | Filter JSON output (implies `-f json`) | -| `-v`, `--verbose` | Print triple/subject counts first | - -## Inspect one document - -Use `--pretty` with a subject-focused SELECT to peek at frontmatter triples in the terminal. Markdown body and typed infobox layout are not reproduced — use [Wiki Subcommand serve](Wiki_Subcommand_serve.md) for full page preview. - -```bash -wiki query --pretty "SELECT ?property ?value WHERE { - wiki:Gregory_Davidson ?property ?value . -}" -``` - -## Graph reuse - -See [Graph Cache](Graph_Cache.md) — one graph per process unless `--reload`, plus optional cross-process warm-start via `--cache`. - -## Source provenance - -Installed sources are exposed as read-only RDF named graphs. Discover graph URIs with [Wiki Subcommand graph](Wiki_Subcommand_graph.md): - -```bash -wiki graph list -``` - -Then scope a query with native SPARQL: - -```sparql -SELECT ?name WHERE { - GRAPH { - ?s schema:name ?name . - } -} -``` - -Or ask which graph supplied each binding: - -```sparql -SELECT ?g ?s WHERE { - GRAPH ?g { - ?s a schema:Thing . - } -} -``` - -This is read-only provenance. It does not mutate installed sources or implement SPARQL Update. - -## HTTP endpoint - -The same query engine backs an optional read-only SPARQL HTTP route when `sparql_service.enabled` is on in `wiki.yaml`. Configure keys and path collision rules in [Wiki Configuration](Wiki_Configuration.md#serve-api); request forms and `Accept` negotiation in [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint). - -## Related - -- [SPARQL](SPARQL.md) -- [Wiki Subcommand graph](Wiki_Subcommand_graph.md) -- [Wiki Subcommand render](Wiki_Subcommand_render.md) -- [Wiki Subcommand serve](Wiki_Subcommand_serve.md#sparql-endpoint) diff --git a/docs/wiki/Wiki_Subcommand_remove.md b/docs/wiki/Wiki_Subcommand_remove.md index 5df3a0b..f837ebc 100644 --- a/docs/wiki/Wiki_Subcommand_remove.md +++ b/docs/wiki/Wiki_Subcommand_remove.md @@ -1,28 +1,7 @@ --- type: TechArticle -headline: wiki remove -description: Remove a data source from wiki.yml, its cache, and wiki.lock. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_remove --- - -# `wiki remove` - -Remove a previously installed source by name. Deletes the source entry from the `sources:` block in `wiki.yml`, removes the cached repository under `.wiki/sources//`, and deletes the entry from `wiki.lock`. - -**Transitive dependency cleanup:** when a source is removed, transitive sources that are no longer required by any remaining top-level source are automatically cleaned up — their cache and lockfile entries are removed too. - -## Usage - -```bash -wiki remove shared-taxonomy -``` - -## Arguments - -| Argument | Description | -| -------- | --------------------------------------------------------- | -| `name` | Name of the source to remove (as declared in `wiki.yml`). | - -## Related - -- [Wiki Subcommand install](Wiki_Subcommand_install.md) -- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) diff --git a/docs/wiki/Wiki_Subcommand_render.md b/docs/wiki/Wiki_Subcommand_render.md index d8e062a..dcd74cf 100644 --- a/docs/wiki/Wiki_Subcommand_render.md +++ b/docs/wiki/Wiki_Subcommand_render.md @@ -1,164 +1,7 @@ --- type: TechArticle -headline: wiki render -description: Update inline SPARQL result tables in markdown files. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_render --- - -# `wiki render` - -Find `<!-- sparql:start -->` ... `<!-- sparql:end -->` regions in markdown, run the embedded query against the wiki graph, and rewrite the table (or `(no results)`) in place. - -Silent on success by default. See [Design Philosophies](Design_Philosophies.md). - -## Usage - -```bash -wiki render -wiki render wiki/Report.md -wiki render wiki/people/alpha.md wiki/projects/beta.md -wiki render wiki/people/*.md -wiki render -v -wiki render --check -wiki render --no-inference -wiki render --reload -wiki render --cache -``` - -## Options - -| Flag | Description | -| ----------------- | -------------------------------------------------------------------------------------- | -| `FILE...` | Optional `.md` paths; otherwise entire wiki (shell globs expand to multiple FILE args) | -| `--check` | Dry-run; exit 1 if any block is stale | -| `--no-inference` | Skip OWL-RL | -| `--reload` | Rebuild graph before rendering | -| `--cache` | Persist a warm graph under `.wiki/cache/` for reuse across new processes | -| `-v`, `--verbose` | Print update counts | - -## Block format - -See [Style Guide](Style_Guide.md) for the `sparql:start` / `sparql:end` wrapper and fenced `sparql` code block. Close the start comment before the fence to show the query in built HTML. Leave it open and close after the fence to hide the query from published pages while `wiki render` still updates the table. - -## Examples - -### List all people (visible query) - -The default visible block style shows the query in published HTML so readers can see and learn from it. - - -```sparql -PREFIX rdf: -PREFIX schema: - -SELECT ?person ?givenName ?familyName WHERE { - ?person rdf:type schema:Person . - ?person schema:givenName ?givenName . - ?person schema:familyName ?familyName . -} -ORDER BY ?familyName -``` - -| person | givenName | familyName | -| --- | --- | --- | -| [Jeff_Kazzee](Jeff_Kazzee.md) | Jeff | Kazzee | -| https://wiki.example.org/people/Alice_Smith | Alice | Smith | - - -### List all software applications (hidden query) - -The hidden query style keeps the SPARQL inside an HTML comment — invisible in published pages, but still executed by `wiki render`. - - -| app | name | version | -| --- | --- | --- | -| [Linked_Markdown](Linked_Markdown.md) | Linked Markdown | | -| [Obsidian](Obsidian.md) | Obsidian | | -| [Vivary](Vivary.md) | Vivary | 0.1.0 | -| [Wiki_CLI](Wiki_CLI.md) | Wiki CLI | 0.1.21 | - - -### More query patterns - -Paste one of these SPARQL queries into a `sparql:start` block on any wiki page and run `wiki render` to see results. - -**All TechArticles with headlines and descriptions:** - -```sparql -PREFIX rdf: -PREFIX schema: - -SELECT ?headline ?description WHERE { - ?doc rdf:type schema:TechArticle . - ?doc schema:headline ?headline . - OPTIONAL { ?doc schema:description ?description . } -} -ORDER BY ?headline -``` - -**Full-text search for pages that mention a term in their body:** - -```sparql -PREFIX rdf: -PREFIX schema: - -SELECT ?headline WHERE { - ?doc rdf:type schema:TechArticle . - ?doc schema:headline ?headline . - ?doc schema:articleBody ?body . - FILTER(CONTAINS(?body, "your-search-term")) -} -ORDER BY ?headline -``` - -**Backlinks to a target page via body text:** - -```sparql -PREFIX rdf: -PREFIX schema: - -SELECT ?headline WHERE { - ?doc rdf:type schema:TechArticle . - ?doc schema:headline ?headline . - ?doc schema:articleBody ?body . - FILTER(CONTAINS(?body, "Target_Page")) -} -ORDER BY ?headline -``` - -Replace `"Target_Page"` with a page filename (without `.md`) to find pages that link to it. - -**Recent changes by date (requires date frontmatter):** - -Add `dateCreated` or `dateModified` to your page frontmatter with a YAML date (e.g. `dateCreated: 2026-06-28`). The wiki graph automatically types these as `xsd:date`. Then query: - -```sparql -PREFIX rdf: -PREFIX schema: - -SELECT ?headline ?created WHERE { - ?doc rdf:type schema:TechArticle . - ?doc schema:headline ?headline . - ?doc schema:dateCreated ?created . -} -ORDER BY DESC(?created) -``` - -## Related - -- [SPARQL](SPARQL.md) -- [Style Guide](Style_Guide.md) — `sparql:start` / `sparql:end` block format -- [Graph Cache](Graph_Cache.md) -- [Wiki Subcommand query](Wiki_Subcommand_query.md) -- [Wiki Subcommand build](Wiki_Subcommand_build.md) — `wiki build --render` diff --git a/docs/wiki/Wiki_Subcommand_serve.md b/docs/wiki/Wiki_Subcommand_serve.md index 5652451..b03fbbf 100644 --- a/docs/wiki/Wiki_Subcommand_serve.md +++ b/docs/wiki/Wiki_Subcommand_serve.md @@ -1,105 +1,7 @@ --- type: TechArticle -headline: wiki serve -description: Local HTTP server for live HTML preview and optional read-only SPARQL endpoint. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_serve --- - -# `wiki serve` - -Start a development server that renders wiki pages on demand. - -## Usage - -```bash -wiki serve -wiki serve --host 0.0.0.0 --port 3000 -wiki serve --watch -wiki serve --site-base-url /my-wiki --site-url-style dir -python -m wiki serve --watch -``` - -## Options - -| Flag | Default | Description | -| ------------------ | ----------- | ----------------------------------------------------------- | -| `--host` | `127.0.0.1` | Bind address | -| `--port` | `8080` | Port | -| `--site-base-url` | from config | Override `site.base_url` page URL prefix | -| `--site-url-style` | from config | Override `site.url_style`: `dir` or `file` | -| `--watch` | off | Rebuild graph, SPARQL blocks, and reload browser on changes | - -Default URL with config `site.base_url: /wiki`: `http://127.0.0.1:8080/wiki/`. - -## SPARQL endpoint - -When `sparql_service.enabled` is on, `wiki serve` also exposes a read-only SPARQL endpoint at `sparql_service.path` (default `/api/sparql`). See [Wiki Configuration](Wiki_Configuration.md#serve-api) for config keys, opt-in defaults, and path collision rules. - -A bare `GET` on that path (no query string) returns a [SPARQL 1.1 Service Description](https://www.w3.org/TR/sparql11-service-description/) document (OWL-RL as the default entailment profile, supported result formats, default dataset triple count when available). Content negotiation applies: `text/turtle`, `application/rdf+xml`, or `application/n-triples`. - -Example config: - -```yaml -sparql_service: - enabled: true - path: /api/sparql -``` - -### Supported query forms - -`SELECT`, `ASK`, `CONSTRUCT`, and `DESCRIBE` are accepted. SPARQL Update is rejected with `405`. - -### Request forms - -```bash -# Service description (SPARQL 1.1 Service Description) -curl "http://127.0.0.1:8080/api/sparql" -H "Accept: text/turtle" - -# GET with query string -curl "http://127.0.0.1:8080/api/sparql?query=SELECT%20*%20WHERE%20%7B%20?s%20?p%20?o%20%7D" \ - -H "Accept: application/sparql-results+json" - -# POST raw SPARQL query -curl "http://127.0.0.1:8080/api/sparql" \ - -H "Content-Type: application/sparql-query" \ - -H "Accept: text/turtle" \ - --data "CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }" - -# POST application/x-www-form-urlencoded (query= plus optional inference/reload) -curl "http://127.0.0.1:8080/api/sparql" \ - -H "Content-Type: application/x-www-form-urlencoded" \ - -H "Accept: application/sparql-results+json" \ - --data "query=ASK%20%7B%20%3Fs%20%3Fp%20%3Fo%20%7D" -``` - -Use the `Accept` header to choose the response serialization. Unsupported values return `406`. - -| Query form | Accepted `Accept` values | -| ----------------------- | ------------------------------------------------------------------------------------ | -| `SELECT`, `ASK` | `application/sparql-results+json` (default), `text/csv`, `text/tab-separated-values` | -| `CONSTRUCT`, `DESCRIBE` | `text/turtle` (default), `application/n-triples`, `text/n3` | - -Wiki-specific query parameters (GET query string, or form body on `application/x-www-form-urlencoded` POST): - -- `inference=true|false` — OWL-RL inference (default `true`; mirrors `wiki query` unless `--no-inference`) -- `reload=true|false` — rebuild the in-memory graph before executing (default `false`) - -The endpoint reuses the same query engine as [Wiki Subcommand query](Wiki_Subcommand_query.md). - -For safety, the endpoint is **disabled by default**. Its path is validated at startup and rejected if it would shadow page routes or the `__watch` endpoint. - -## Wiki page layout - -The same `site.layout` from [Wiki Configuration](Wiki_Configuration.md#page-layout) applies to the dev server — a page layout (`.html`; packaged `index.html` when unset). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md). Page bodies use the same markdown renderer as `wiki build`; raw HTML in markdown is not emitted as live markup. - -## Metadata view - -The live page metadata panel supports RDF formats without JavaScript: compacted JSON-LD, Turtle, N3, RDF/XML, N-Triples, TriG, and N-Quads. A compact **Format** chip row selects the view. Set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). See [Content Negotiation](Content_Negotiation.md) for the HTTP `Accept` model. - -## Related - -- [Wiki Subcommand build](Wiki_Subcommand_build.md) -- [Wiki Subcommand query](Wiki_Subcommand_query.md) -- [SPARQL](SPARQL.md) -- [Graph Cache](Graph_Cache.md) -- [Wiki Configuration](Wiki_Configuration.md#serve-api) -- [Content Negotiation](Content_Negotiation.md) diff --git a/docs/wiki/Wiki_Subcommand_update.md b/docs/wiki/Wiki_Subcommand_update.md index 66d6e22..9982adc 100644 --- a/docs/wiki/Wiki_Subcommand_update.md +++ b/docs/wiki/Wiki_Subcommand_update.md @@ -1,39 +1,7 @@ --- type: TechArticle -headline: wiki update -description: Check locked sources for newer commits and update wiki.lock. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_update --- - -# `wiki update` - -Fetch each locked source, resolve the current HEAD (or the configured ref), and compare against the pinned commit in `wiki.lock`. If the commit has changed, update the lockfile entry. - -This is the incremental counterpart to `wiki install` — it only writes the lockfile when something actually changed, and reports what updated. - -**Transitive dependency re-sync:** after updating commits, `wiki update` re-discovers each source's declared transitive dependencies. Newly declared sources are automatically installed and locked. Orphaned sources (transitive deps that were dropped by a source's new commit) are reported as warnings but not automatically removed — run `wiki remove ` to clean up. - -## Usage - -```bash -wiki update -wiki update solar-system -wiki update --dry-run -``` - -## Arguments - -| Argument | Description | -| -------- | ------------------------------------------------------- | -| `name` | Source name to check. Omit to check all locked sources. | - -## Options - -| Flag | Description | -| ----------------- | ----------------------------------------------------- | -| `-n`, `--dry-run` | Show what would update without modifying `wiki.lock`. | - -## Related - -- [Wiki Subcommand install](Wiki_Subcommand_install.md) -- [Wiki Subcommand remove](Wiki_Subcommand_remove.md) -- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) diff --git a/docs/wiki/Wiki_Subcommand_upgrade.md b/docs/wiki/Wiki_Subcommand_upgrade.md index 9d54b39..6e2d0ff 100644 --- a/docs/wiki/Wiki_Subcommand_upgrade.md +++ b/docs/wiki/Wiki_Subcommand_upgrade.md @@ -1,49 +1,7 @@ --- type: TechArticle -headline: wiki upgrade -description: Check PyPI for updates and upgrade wazootech-wiki. +headline: Redirecting... +description: Redirect page +wazoo:layout: layouts/redirect.html +redirect_to: wiki_upgrade --- - -# `wiki upgrade` - -Compare the installed **wazootech-wiki** version to PyPI and optionally upgrade with pip. - -## Usage - -```bash -wiki upgrade -c # check only; exit 1 if outdated -wiki upgrade # prompt to upgrade when outdated -wiki upgrade -y # upgrade without prompt -wiki upgrade -y -v # show pip output -``` - -## Options - -| Flag | Description | -| ----------------- | ---------------------------------- | -| `-c`, `--check` | Report status only; do not install | -| `-y`, `--yes` | Skip confirmation | -| `-v`, `--verbose` | Show pip install logs | - -## Windows PATH troubleshooting - -If `python -m wiki upgrade` works but `wiki upgrade` says `No such command 'upgrade'`, PATH is probably resolving `wiki` to an older `wiki.exe` from a different Python install. - -Check which launcher is active: - -```powershell -Get-Command wiki -where.exe wiki -python -m wiki --help -``` - -If the PATH launcher is stale, upgrade through the intended interpreter and remove or refresh the older shim: - -```powershell -python -m wiki upgrade -y -python -m pip install --upgrade wazootech-wiki -``` - -## Related - -- [Getting Started](Getting_Started.md) diff --git a/docs/wiki/wiki.md b/docs/wiki/wiki.md new file mode 100644 index 0000000..cbec900 --- /dev/null +++ b/docs/wiki/wiki.md @@ -0,0 +1,319 @@ +--- +type: schema:SoftwareApplication +name: Wiki CLI +softwareVersion: 0.1.21 +description: Command-line interface for querying, validating, and publishing semantic markdown wikis. +codeRepository: https://github.com/wazootech/wiki +--- + +# `wiki` + +This page is the **documentation home** for **Wiki CLI** (`wiki` on PyPI and npm as [**`wazootech-wiki`**](https://pypi.org/project/wazootech-wiki/)): the semantic knowledge **toolchain** for Markdown wikis — validate with [SHACL](SHACL.md) and JSON Schema, infer and query with [SPARQL](SPARQL.md), and publish static HTML. It compiles wikis into RDF and sits **beneath** note apps and LLM-assisted workflows — progressive enhancement, not a migration. + +```bash +pip install wazootech-wiki +wiki --help +``` + +Install options: PyPI (`pip install wazootech-wiki`), npm ([`wazootech-wiki` on npm](https://www.npmjs.com/package/wazootech-wiki) → `wiki` on PATH), or zero-install (`npx wazootech-wiki` / `uvx wazootech-wiki` — same subcommands as `wiki`). See [Getting Started](Getting_Started.md#install). + +## Quickstart + +```bash +pip install wazootech-wiki +mkdir my-wiki && cd my-wiki +wiki init +wiki check +wiki lint +wiki serve +``` + +See [Getting Started](Getting_Started.md) for a full walkthrough. + +## What wiki is + +- The **compiler / validator / query engine** for Markdown knowledge bases with semantic frontmatter +- An **OOTB wiki builder** — links, navigation, SHACL and JSON Schema checks, SPARQL, and static HTML from a folder of `.md` files +- A **memory layer** — ingest or watch an existing wiki without owning the editor +- **Interop-first** — works alongside [Obsidian](Obsidian_Integration.md), [LLM Wiki](LLM_Wiki.md) setups, and any Markdown editor + +Adoption path: `wiki init` → `wiki check` → `wiki serve`, then add `lint`, `query`, `render`, and `build` as the wiki matures. + +Wiki CLI is intentionally batteries-included for semantic Markdown wikis: validation, formatting, querying, rendering, exporting, building, and local preview belong together. The boundary is not "minimal CLI only"; the boundary is "semantic wiki toolchain, not editor/app automation." + +## What wiki is not + +- The **primary editor** or daily note-taking surface +- A **replacement** for Obsidian, Logseq, or another wiki UI +- A **note app clone**, CMS, or authenticated multi-user web product +- An **auth layer** — local-first CLI and static publish; see deferred scope in [Wiki CLI templates](#ecosystem-templates) below +- A vault automation CLI for daily notes, note append/read workflows, task lists, tags, plugin development, or Obsidian app control +- A replacement for shell tools, Git, Pandoc, or editor-native commands + +Humans and agents keep writing where they already write. `wiki` makes that content **trustworthy** (SHACL, JSON Schema, and conventions), **searchable** (SPARQL + OWL-RL), and **publishable** (static HTML, JSON-LD, Turtle, optional read-only SPARQL over `wiki serve`). + +## Memory layer and ingestion + +Rather than owning your editor or data store, **Wiki** functions as a **read-only memory layer** over your wiki. It parses, indexes, and queries the Markdown documents on your filesystem without mutating them or locking you into a proprietary format. + +- **Ingestion:** The CLI reads YAML/JSON frontmatter and HTML microdata from your files, compiling them into an in-memory RDF graph that can be queried with SPARQL or verified against SHACL shapes and JSON Schema bindings. +- **Watching:** Running `wiki serve --watch` instructs the CLI to watch the wiki directory. Any edits you make in your preferred editor are immediately processed, updating the graph in the background and keeping your preview server synchronized. + +## Toolchain vs authoring surface + +| Layer | Role | Examples | +| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------- | +| Authoring surface | Create, edit, search, and organize notes | Obsidian CLI, Obsidian, VS Code, shell | +| Wiki CLI semantic layer | Compile wiki → RDF graph; check, lint, fmt; query; render; build/serve | `wiki check`, `wiki query`, `wiki build` | +| Existing primitives | History, sync, print/PDF, and generic text processing | Git, shell tools, Pandoc | +| Outputs | Deployable semantic artifacts | GitHub Pages HTML, export files, `/api/sparql` when enabled | + +This separation is intentional: the strongest differentiator is the **machine layer** (SHACL, OWL-RL, SPARQL, typed HTML) that most note apps do not provide. **Wiki** avoids competing with editor-centric tools while making incremental adoption obvious. + +When an existing primitive already owns a workflow, Wiki CLI integrates rather than replaces it. Obsidian CLI owns Obsidian app/vault automation; Git owns history and collaboration; shell tools own generic file/process composition; Pandoc and document tools own non-semantic document conversion. + +`wiki link --fix-broken` supports link hygiene for publishable wikis. `wiki link --apply` is optional wiki-gardening: useful when desired, but not required for validation, publishing, or Obsidian compatibility. + +## Interop-first workflows + +### Obsidian + +Run `wiki` against the folder that contains `wiki.yml` or `wiki.yaml`. Use Shell Commands for on-save `wiki check`, hotkey `wiki render`, or `wiki serve --watch` for preview. Details: [Obsidian integration](Obsidian_Integration.md) and [Dataview integration](Dataview_Integration.md). + +### LLM wikis + +Treat the wiki as a compounding codebase agents maintain over time. Structured frontmatter and link conventions make SPARQL and SHACL meaningful on agent output. Pattern overview: [LLM Wiki](LLM_Wiki.md). + +### Plain Markdown + +No Obsidian or agent stack required. `wiki init` scaffolds a wiki; conventions are documented in [Style Guide](Style_Guide.md). + +## Three capabilities of the CLI + +| Capability | Commands | Value | +| ------------ | ---------------------------------- | ------------------------------------------------------------------ | +| Trust | `check`, `lint`, `fmt` | Integrity contracts and authoring conventions | +| Intelligence | `query`, `mcp`, `render`, `export` | SPARQL, MCP graph access, inline result blocks, RDF serializations | +| Publish | `build`, `serve`, `link` | Static site, local preview, wikilink hygiene | +| Sources | `install`, `update`, `remove` | Fetch, lock, update, and manage external sources | +| Provenance | `graph list` | Inspect read-only named graph boundaries | + +Design rationale for silence, pipes, and flat subcommands: [Design philosophies](Design_Philosophies.md). + +## Ecosystem templates + +GitHub **template repositories** in the [wazootech](https://github.com/wazootech) org sit at the edges of the toolchain — publish surfaces, query UIs, and starter vaults — while Wiki CLI owns the semantic layer ([Design philosophies](Design_Philosophies.md)). This section is the canonical registry. + +| Template | Description | +| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [wiki-template](https://github.com/wazootech/wiki-template) | Generic Wiki CLI project (`wiki init` parity plus deploy) | +| [wiki-yasgui-template](https://github.com/wazootech/wiki-yasgui-template) | SPARQL query editor UI (YASGUI); `wiki serve` `/api/sparql`, export TTL ([#14](https://github.com/wazootech/wiki/issues/14), [#81](https://github.com/wazootech/wiki/issues/81)) | +| [llm-wiki-template](https://github.com/wazootech/llm-wiki-template) | [LLM Wiki](LLM_Wiki.md) starter vault with agent-oriented pages and gardening hooks ([#83](https://github.com/wazootech/wiki/issues/83)) | +| [wiki-nextjs-template](https://github.com/wazootech/wiki-nextjs-template) | Next.js SSG consumer of `wiki export` JSON-LD ([#15](https://github.com/wazootech/wiki/issues/15)) | +| [wiki-quartz-template](https://github.com/wazootech/wiki-quartz-template) | Quartz static site from a compatible vault plus `wiki check` CI ([#16](https://github.com/wazootech/wiki/issues/16)); Obsidian remains a supported authoring surface — the slug does not include `obsidian` | +| [wiki-mintlify-template](https://github.com/wazootech/wiki-mintlify-template) | Mintlify or Holocron docs site from a compatible vault ([#31](https://github.com/wazootech/wiki/issues/31)) | +| [wiki-astro-template](https://github.com/wazootech/wiki-astro-template) | Astro SSG consumer of `wiki export` JSON-LD ([#96](https://github.com/wazootech/wiki/issues/96)) | + +### Artifact contract + +External templates consume Wiki CLI outputs — they do not replace the compiler: + +- **`wiki.yml`** / **`wiki.yaml`** — config root; `wiki.inputs`, `graph.*`, `site.*` +- **`wiki export`** — JSON-LD, Turtle, TriG, and other RDF serializations +- **`wiki build`** — static HTML under `site.base_url` + +### Retired slugs + +Do not use these in new prose: `sparql-service-template` (→ `wiki-yasgui-template`); `wiki-virtuoso-template` (→ folded into `wiki-yasgui-template`); `wiki-obsidian-quartz-template`, `obsidian-quartz-template` (→ `wiki-quartz-template`); bare `nextjs-template`, `mintlify-template`, `astro-template` (→ `wiki-*` counterparts). + +## Features + +- **Check** — SHACL and JSON Schema integrity, route safety, layout frontmatter ([wiki check](wiki_check.md)) +- **Lint** — broken links, filename pattern, and heading conventions ([wiki lint](wiki_lint.md)) +- **Link** — repair broken internal links and optionally insert suggested links as wiki-gardening ([wiki link](wiki_link.md)) +- **Fmt** — mdformat for markdown ([wiki fmt](wiki_fmt.md)) +- **Query** — SPARQL with OWL-RL and optional `--pretty` Rich tables ([wiki query](wiki_query.md), [Graph Cache](Graph_Cache.md)) +- **Graph list** — inspect root and source named graphs for SPARQL `GRAPH` provenance ([wiki graph](wiki_graph.md)) +- **MCP** — read-only query-first MCP server for local agents ([wiki mcp](wiki_mcp.md)) +- **Render** — live tables from inline SPARQL ([wiki render](wiki_render.md)) +- **Build / serve** — static site, local preview, and optional read-only SPARQL endpoint ([wiki build](wiki_build.md), [wiki serve](wiki_serve.md#sparql-endpoint)) +- **Export** — JSON-LD and RDF serializations ([wiki export](wiki_export.md)) +- **Install** — fetch and lock external data sources ([wiki install](wiki_install.md)) +- **Update** — check locked sources for newer commits ([wiki update](wiki_update.md)) +- **Remove** — delete a source from wiki.yml, cache, and lockfile ([wiki remove](wiki_remove.md)) +- **Init** — scaffold `wiki.yml` ([wiki init](wiki_init.md)) +- **Upgrade** — PyPI updates ([wiki upgrade](wiki_upgrade.md)) + +## Supported file formats + +### Input pipelines + +Wiki CLI processes files through two distinct pipelines. Files in `wiki.inputs` are classified as either **documents** (frontmatter parsed, IRI derived from file path, link-checked) or **raw RDF sources** (loaded directly via rdflib, no document processing): + +| Category | Extensions | Pipeline | Key behavior | +| ------------------- | -------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- | +| Wiki documents | `.md`, `.yaml`, `.yml`, `.json`, `.toml` | Frontmatter → graph | Parsed for frontmatter/data; document IRI derived from file path; link-checked and exportable | +| Data-only documents | `.yaml`, `.yml`, `.json`, `.toml` | Frontmatter → graph | Subset of wiki documents without a markdown body — entire file is the data dict | +| Raw RDF sources | `.ttl`, `.trig`, `.nt`, `.nq`, `.rdf`, `.xml`, `.jsonld` | rdflib parse → graph | Loaded as raw triples; no route, no link checking, no frontmatter pipeline | +| Inline Turtle | Inside `.md` as ```` ```turtle ```` blocks | rdflib parse → graph | Fenced turtle blocks inside markdown files are parsed and merged into the graph | + +### Document pipeline + +Markdown files are parsed via the [Linked Markdown](Linked_Markdown.md) protocol: the YAML/JSON frontmatter between `---` delimiters is extracted as the data dict, and the body text is optionally added to the graph via `content_predicate`. Data-only documents (`.yaml`, `.yml`, `.json`, `.toml`) skip the body split — the entire file is the data. + +All document formats have their `@context` auto-populated with `wiki:` and `foaf:` default prefixes if none is present. An explicit `@id` or `id` key in frontmatter overrides the file-path-based IRI ([Linked Markdown](Linked_Markdown.md#subject-uri-resolution)). + +### Raw RDF pipeline + +Files with raw RDF extensions are parsed directly by rdflib using the format mapped from their extension. They bypass all document processing — no route registration, no link validation, no frontmatter coercion. They contribute triples to the same graph but are invisible to `wiki export` (which operates on documents) and `wiki link`. + +**Important nuance:** `.jsonld` is raw RDF (rdflib `json-ld` format) — it is NOT a wiki document. It does not get a document IRI, does not go through `ensure_context()`, and is not subject to link checking. A `.json` file with the same content *is* a wiki document and follows the frontmatter pipeline. These are disjoint processing paths. + +### Output formats + +| Context | Formats | +| ----------------------------------------- | -------------------------------------------------------------------------- | +| `wiki export` | `dict` (default), `json-ld`, `turtle`, `xml`, `n3`, `nt`, `trig`, `nquads` | +| `wiki query` | `table` (default), `json`, `csv`, `tsv`, `turtle`, `n3`, `markdown` | +| `wiki serve` / `wiki build` metadata view | `json-ld`, `turtle`, `n3`, `xml`, `nt`, `trig`, `nquads` | + +### Key nuances + +- **`.jsonld` vs `.json`** — Different pipelines for the same data shape. See raw RDF pipeline note above. +- **N3 is output-only** — Notation3 (`.n3`) is available for `wiki export` and `wiki query` CONSTRUCT results but is not recognized as an input graph source extension. +- **`@context` auto-injection** — Document files that lack an `@context` key get default `wiki:` and `foaf:` prefixes injected. If `@context` is present as a dict, those defaults are merged in. +- **Only `.md` carries body text** — Data-only formats cannot carry a body literal in the graph; the entire file content is the data dict. +- **Inline ```` ```turtle ``` ```` blocks** — Any fenced code block with `turtle` language inside a `.md` file is parsed as Turtle RDF and merged into the wiki graph. This is separate from SPARQL result blocks. +- **`.toml` is a document format** — TOML files under `wiki.inputs` are treated as data-only wiki documents, subject to `@context` injection and route generation. + +### Related + +- [Linked Markdown](Linked_Markdown.md) — document-to-RDF protocol and IRI resolution +- [RDF](RDF.md) — RDF data model and serialization references +- Individual format pages: [Turtle](Turtle.md), [TriG](TriG.md), [N-Triples](N_Triples.md), [N-Quads](N_Quads.md), [RDF/XML](RDF_XML.md), [Notation3](Notation3.md), [JSON-LD](JSON_LD.md) + +## Agent skills + +Procedural knowledge for coding agents: [Wiki Skills](Wiki_Skills.md) (`skills/wiki/` in the repository). + +## Start here + +- [Getting Started](Getting_Started.md) — install, `wiki init`, first `check` and `serve` +- [Wiki Configuration](Wiki_Configuration.md) — `wiki.yml` / `wiki.yaml` options +- [Style Guide](Style_Guide.md) — frontmatter, shapes, internal links, SPARQL blocks +- [Graph Cache](Graph_Cache.md) — in-process RDF graph reuse +- [Design Philosophies](Design_Philosophies.md) — silence is golden, pipes, flat commands + +## Global Options + +These options apply to config-loading subcommands (`check`, `lint`, `link`, `query`, `mcp`, `render`, `build`, `export`, `serve`, `fmt`, `install`, `remove`). `init` and `upgrade` do not load a config file. + +### `-c, --config PATH` + +Path to `wiki.yml`, `wiki.yaml`, `wiki.json`, or a directory containing one of those files. Defaults to the current directory (`.`). + +Example: + +```bash +wiki -c docs/wiki.yml check +``` + +### `--wiki-inputs PATH` (repeatable) + +Override or extend `wiki.inputs` from config for a single invocation. Relative paths resolve against the config file directory. Useful for one-off queries against a subdirectory. + +Example: + +```bash +wiki --wiki-inputs ./wiki --wiki-inputs ./imported query "SELECT * WHERE { ?s ?p ?o } LIMIT 5" +``` + +## Command reference + +Each subcommand has a dedicated page: + + + +| command | description | +| --- | --- | +| [wiki_build](wiki_build.md) | Generate a static HTML site from the wiki. | +| [wiki_check](wiki_check.md) | Integrity checks — SHACL validation, JSON Schema frontmatter, route safety, and layout frontmatter. | +| [wiki_export](wiki_export.md) | Export document frontmatter as RDF or JSON-LD. | +| [wiki_fmt](wiki_fmt.md) | Format markdown wiki pages using mdformat with wikilink preservation. | +| [wiki_graph](wiki_graph.md) | List read-only RDF named graphs for root and installed source provenance. | +| [wiki_init](wiki_init.md) | Scaffold wiki.yml and starter wiki pages interactively. | +| [wiki_install](wiki_install.md) | Fetch and lock external data sources declared in wiki.yml. | +| [wiki_link](wiki_link.md) | Suggest missing wikilinks and repair unambiguous broken internal links. | +| [wiki_lint](wiki_lint.md) | Convention audits for broken links, filename patterns, heading style, and internal link style. | +| [wiki_mcp](wiki_mcp.md) | Run a read-only MCP server for querying the wiki graph. | +| [wiki_query](wiki_query.md) | Run SPARQL SELECT or CONSTRUCT against the wiki graph. | +| [wiki_remove](wiki_remove.md) | Remove a data source from wiki.yml, its cache, and wiki.lock. | +| [wiki_render](wiki_render.md) | Update inline SPARQL result tables in markdown files. | +| [wiki_serve](wiki_serve.md) | Local HTTP server for live HTML preview and optional read-only SPARQL endpoint. | +| [wiki_update](wiki_update.md) | Check locked sources for newer commits and update wiki.lock. | +| [wiki_upgrade](wiki_upgrade.md) | Check PyPI for updates and upgrade wazootech-wiki. | + + + +Global flags: `-c`, `--wiki-inputs`. + +## Publishing + +- [Deploying to GitHub Pages](Deploying_to_GitHub_Pages.md) — CI workflow for this site +- [Obsidian Integration](Obsidian_Integration.md) — Shell Commands plugin workflows + +## Managing drift and schema evolution + +A common challenge in text-based memory bases is metadata drift—especially when files are updated programmatically by external LLM agents. The Wiki CLI provides two strategies to keep a compounding codebase clean over long periods: + +### Automated cleaning harness + +To prevent drift mechanically, you can wire a local Git hook or CI workflow that executes the following checks in order: + +1. **[wiki fmt](wiki_fmt.md)**: Auto-formats Markdown structures and standardizes YAML frontmatter layout. +1. **[wiki lint](wiki_lint.md) `--strict`**: Flags broken links, non-conforming filename patterns, and heading casing warnings as hard errors. +1. **[wiki check](wiki_check.md) `--strict`**: Ensures frontmatter conforms to [SHACL](SHACL.md) shapes and bound JSON Schema documents (`wazoo:jsonSchema`). + +### Resilient schema evolution + +Enforcing schemas on text databases can become problematic as structures evolve. The Wiki CLI avoids schema rigidity using semantic web principles: + +- **Additive RDF properties**: Since frontmatter is compiled into a graph, new or unconstrained keys do not cause parsing failures. They are ingested as open-world triples that can be queried or ignored. +- **Decoupled validation**: SHACL and JSON Schema validation are diagnostic steps, not execution blockers. Files with invalid schemas can still be compiled, parsed, and queried. +- **Class-scoped shapes**: Shapes target specific classes (e.g., `sh:targetClass schema:TechArticle`). Introducing a new document type only requires writing a new shape constraint, leaving legacy documents untouched. +- **Namespace contexts**: Properties map to URIs via `graph.context` in [Wiki Configuration](Wiki_Configuration.md). You can rename or alias fields at the config layer without physically editing every source document. + +## Design + +The CLI follows a flat, scriptable surface and [Design Philosophies](Design_Philosophies.md) (silent success, composable stdout). For programmatic use from Python or TypeScript, see [Wiki Programmatic API](Wiki_Programmatic_API.md). + +## Pattern context + +This repository implements the [LLM Wiki](LLM_Wiki.md) pattern for [Personal Knowledge](Personal_Knowledge.md) wikis. Examples in the wild include [Farzapedia](Farzapedia.md) and coverage from Andrej Karpathy. + +Similar **agent memory filesystem** approaches include [Supermemory SMFS](Supermemory_SMFS.md), [Letta MemFS](Letta_MemFS.md), and [Agent Memory Filesystems](Agent_Memory_Filesystems.md). + +For a **standardized agent workspace** (typed graph, loop, blast-radius review), see [Vivary](Vivary.md). + +## Repository + +- Source and issues: [github.com/wazootech/wiki](https://github.com/wazootech/wiki) +- [Wiki CLI templates](#ecosystem-templates) — generic starter [wiki-template](https://github.com/wazootech/wiki-template); [LLM Wiki](LLM_Wiki.md) starter [llm-wiki-template](https://github.com/wazootech/llm-wiki-template) + +## Background + +- [Semantic Web](Semantic_Web.md) — RDF, Turtle, OWL, and related formats +- [Software Application Shape](Software_Application_Shape.md) — SHACL shape for `SoftwareApplication` pages (including this page) diff --git a/docs/wiki/wiki_build.md b/docs/wiki/wiki_build.md new file mode 100644 index 0000000..87b180d --- /dev/null +++ b/docs/wiki/wiki_build.md @@ -0,0 +1,68 @@ +--- +type: TechArticle +headline: wiki build +description: Generate a static HTML site from the wiki. +--- + +# `wiki build` + +Compile markdown and data files into static HTML with wikilinks, backlinks, table of contents, and typed templates/infoboxes. Pages with frontmatter embed all metadata format views so the chip picker works without JavaScript. + +## Usage + +```bash +wiki build +wiki build --output-dir _site --site-base-url /wiki -v +wiki build --site-url-style file +wiki build --site-base-url '' +wiki build --render --reload +wiki build --render --cache +wiki build --no-check +``` + +## Options + +| Flag | Default | Description | +| ------------------ | ----------- | --------------------------------------------------------------- | +| `--output-dir` | `_site` | Site root on disk | +| `--site-base-url` | from config | Override `site.base_url` (`/wiki`, `/my-wiki`, or `''`) | +| `--site-url-style` | from config | Override `site.url_style`: `dir` or `file` | +| `--render` | off | Run [wiki render](wiki_render.md) before building | +| `--reload` | off | Rebuild graph when using `--render` | +| `--cache` | off | Persist a warm graph under `.wiki/cache/` when using `--render` | +| `--no-check` | off | Skip pre-build `lint` then `check` preflight | +| `-v`, `--verbose` | off | List output paths | + +## Output layout + +With `site.base_url: /wiki` and `site.url_style: dir`: + +``` +_site/wiki/Alice/index.html → /wiki/Alice/ +``` + +Assets from `wiki.assets` copy under the same prefix. See [Wiki Configuration](Wiki_Configuration.md). + +## Metadata view + +Each built page embeds compacted JSON-LD plus Turtle, N3, RDF/XML, N-Triples, TriG, and N-Quads. JSON-LD is selected by default; the chip row stays usable without JavaScript. + +## Wiki page layout + +If your [Wiki Configuration](Wiki_Configuration.md#page-layout) sets `site.layout`, every page is rendered through that page layout unless `wazoo:layout` overrides it. The builder substitutes layout slots (see [Layout slots](Wiki_Configuration.md#layout-slots)). + +If the configured page layout file is missing, the packaged `index.html` fallback is used silently. + +## Checks and collisions + +By default, convention (`wiki lint`) then integrity (`wiki check`) preflight must pass before the output directory is wiped and rebuilt. Output path collisions abort the build with errors. + +Wiki page bodies are rendered without raw HTML passthrough; inline HTML tags in markdown are not emitted as live markup in built pages. + +`--output-dir` must point at a disposable directory that does not overlap the wiki config root, input directories, asset directories, or the page layout folder. The build refuses to delete paths that would remove source or config files. + +## Related + +- [Deploying to GitHub Pages](Deploying_to_GitHub_Pages.md) +- [wiki serve](wiki_serve.md) +- [Wiki Configuration](Wiki_Configuration.md#page-layout) diff --git a/docs/wiki/wiki_check.md b/docs/wiki/wiki_check.md new file mode 100644 index 0000000..5bfe772 --- /dev/null +++ b/docs/wiki/wiki_check.md @@ -0,0 +1,83 @@ +--- +type: TechArticle +headline: wiki check +description: Integrity checks — SHACL validation, JSON Schema frontmatter, route safety, and layout frontmatter. +--- + +# `wiki check` + +Run **integrity** checks on the wiki: strict **SHACL** validation, **JSON Schema** frontmatter validation, route safety, output collisions, and layout frontmatter contracts. + +Exits **0 silently** on success unless `-v` is set. See [Design Philosophies](Design_Philosophies.md). + +## Usage + +```bash +wiki check +wiki check wiki/Some_Page.md +wiki check wiki/A.md wiki/B.md +wiki check -v +wiki check --strict +``` + +## Options + +| Flag | Description | +| ----------------- | ------------------------------------------------------------------------------------- | +| `FILE...` | Optional documents; otherwise entire wiki (scoped mode: SHACL + JSON Schema per file) | +| `-v`, `--verbose` | Print warnings | +| `--strict` | Treat warnings as errors (exit 1) | + +## What is checked + +### Full wiki (default) + +`wiki check` with no `FILE` argument runs every check below. + +### Always errors (not configurable) + +- **SHACL** — shapes from wiki frontmatter (`sh:NodeShape`, etc.) on the full RDF graph +- **Route safety** — unsafe path segments (spaces, reserved characters, and similar) +- **Output collisions** — two wiki sources mapping to the same built URL (against default `_site` layout) + +### Configurable (`check.*` in `wiki.yaml`) + +| Rule key | What it audits | +| --------------------- | ------------------------------------------------------------------- | +| `missing_layout_file` | `wazoo:layout` paths that do not resolve to a readable `.html` file | +| `frontmatter_schema` | Frontmatter that fails JSON Schema validation | +| `missing_schema_ref` | `wazoo:jsonSchema` paths or URLs that cannot be loaded | +| `remote_schema_refs` | Policy for remote schema URLs: `allow`, `deny`, or `allowlist` | +| `remote_schema_hosts` | Hostnames allowed when `remote_schema_refs` is `allowlist` | + +Default: `missing_layout_file`, `frontmatter_schema`, and `missing_schema_ref` are `error`. `remote_schema_refs` defaults to `allow`. + +### JSON Schema frontmatter + +Bind schemas on `sh:NodeShape` documents with `wazoo:jsonSchema` and `sh:targetClass`. Type-level schemas apply to every matching page; pages may append extra schemas with their own `wazoo:jsonSchema` (string or list). Local refs resolve under the wiki config root; remote `http(s)` URLs are fetched at check time unless `check.remote_schema_refs` is `deny` or the host is outside `check.remote_schema_hosts` when using `allowlist`. Shape binding documents are excluded from instance validation. See [SHACL](SHACL.md) and [Style Guide](Style_Guide.md#shacl-shapes). + +Broken links, filename pattern, and heading style are **not** part of `wiki check` — use [wiki lint](wiki_lint.md). + +### Scoped mode (one or more FILE args) + +`wiki check path/to/Page.md` (or multiple paths) runs **SHACL and JSON Schema** per file. Route safety, output collisions, and layout frontmatter rules are **full-wiki only**. Cross-document SHACL interactions may only appear in a full-wiki check. Broken links on those pages require `wiki lint` with the same paths. + +`--strict` applies only when warnings exist; scoped mode does not emit warnings today. + +### Related CI commands + +| Command | Purpose | +| --------------------- | ---------------------------------------------------- | +| `wiki lint --strict` | Broken links, filename pattern, headings, link style | +| `wiki fmt --check` | mdformat consistency | +| `wiki render --check` | Stale inline SPARQL result blocks | +| `wiki link --check` | Remaining missing-wikilink opportunities | + +`wiki build` runs `wiki lint` then `wiki check` before writing output unless `--no-check`. + +## Related + +- [Wiki Configuration](Wiki_Configuration.md) — `check.*` severities +- [SHACL](SHACL.md) — shape and JSON Schema binding +- [wiki lint](wiki_lint.md) — convention lane +- [Style Guide](Style_Guide.md) diff --git a/docs/wiki/wiki_export.md b/docs/wiki/wiki_export.md new file mode 100644 index 0000000..0891b8e --- /dev/null +++ b/docs/wiki/wiki_export.md @@ -0,0 +1,50 @@ +--- +type: TechArticle +headline: wiki export +description: Export document frontmatter as RDF or JSON-LD. +--- + +# `wiki export` + +Serialize parsed **frontmatter** (and RDF derived from it) for one file or the whole wiki. + +## Usage + +```bash +wiki export +wiki export wiki/Page.md +wiki export wiki/A.md wiki/B.md +wiki export wiki/Page.md -f turtle +wiki export -f json-ld -o wiki.json +wiki export wiki/Page.md --mode compacted -f json-ld +``` + +## Options + +| Flag | Default | Description | +| ---------------- | ------------- | ---------------------------------------------------------------- | +| `FILE...` | all wiki docs | One or more wiki documents, or omit for entire wiki | +| `-f`, `--format` | `dict` | `dict`, `json-ld`, `turtle`, `xml`, `n3`, `nt`, `trig`, `nquads` | +| `--mode` | `expanded` | `expanded` or `compacted` serialization mode | +| `-o`, `--output` | stdout | Output file | + +## Output shape + +For `dict` and `json-ld`, each entry is `{"name": "", "rdf": ...}`. + +Raw RDF formats (`turtle`, etc.) on a **single** FILE write plain serialization without a JSON wrapper. Multiple FILE args or whole-wiki export with raw formats is not supported — use `dict` or `json-ld`, or export one file at a time. + +`--mode compacted` is most visible for JSON-LD, where it emits `@context` and compacted terms when the wiki context provides them. + +## Related + +- [RDF](RDF.md) +- [RDF XML](RDF_XML.md) +- [Turtle](Turtle.md) +- [JSON LD](JSON_LD.md) +- [Notation3](Notation3.md) +- [N Triples](N_Triples.md) +- [TriG](TriG.md) +- [N Quads](N_Quads.md) +- [XML](XML.md) +- [Style Guide](Style_Guide.md) diff --git a/docs/wiki/wiki_fmt.md b/docs/wiki/wiki_fmt.md new file mode 100644 index 0000000..5ab2bee --- /dev/null +++ b/docs/wiki/wiki_fmt.md @@ -0,0 +1,86 @@ +--- +type: TechArticle +headline: wiki fmt +description: Format markdown wiki pages using mdformat with wikilink preservation. +--- + +# `wiki fmt` + +Format markdown wiki pages in-place using **mdformat**. Mechanical markdown style (ATX headings, list spacing, GFM tables, frontmatter layout) is configured under the top-level **`fmt`** key in `wiki.yaml` (or `wiki.json`). + +## Configuration + +### Inline `fmt` (default) + +`wiki init` scaffolds inline `fmt` in `wiki.yaml`: + +```yaml +fmt: + wrap: "no" + end_of_line: lf + extensions: [gfm, front_matters, wikilink, toc, footnote] +``` + +Keys and values follow [mdformat configuration](https://mdformat.readthedocs.io/en/stable/users/configuration_file.html). Unknown keys fail at config load; invalid values fail at load or when `wiki fmt` reads TOML. + +An empty mapping (`fmt: {}`) is valid and resolves to the same **Wiki CLI fmt defaults** as omitting `fmt` when no TOML file applies (`wrap: "no"`, `end_of_line: lf`, extensions `gfm`, `front_matters`, `wikilink`, `toc`, `footnote`). + +### Pointer mode (optional TOML file) + +Instead of an inline mapping, set `fmt` to a **relative path** from the config file directory: + +```yaml +fmt: .mdformat.toml +``` + +Create the file beside `wiki.yaml` with the same keys as inline `fmt` (for example `wrap = "no"`, `end_of_line = "lf"`, `extensions = ["gfm", "frontmatter", "wikilink", "toc", "footnote"]`). Absolute paths are rejected at config load. + +### Resolution order + +`wiki fmt` stops at the **first** source below. Inline `fmt` always wins — it never merges with a `.mdformat.toml` on disk. + +1. **Inline** — `fmt:` mapping in `wiki.yaml` (`fmt: {}` counts as inline and uses Wiki CLI defaults) +1. **Pointer** — TOML at the relative path in `fmt:` +1. **Wiki TOML** — `config_root/.mdformat.toml` when `fmt` is omitted or the pointer file is missing +1. **Parent walk** — nearest `.mdformat.toml` above the markdown file (mdformat behavior) +1. **Defaults** — Wiki CLI fmt defaults (`wrap: "no"`, `end_of_line: lf`, `gfm` / `front_matters` / `wikilink` / `toc` / `footnote`) + +`wiki fmt -v` prints which step matched (for example `Using inline fmt in wiki config.`). + +| Concern | Command | Config | +| --------------------- | ------------- | ------------------------------------------------ | +| Mechanical markdown | `wiki fmt` | `fmt:` in `wiki.yaml` (inline or path) | +| Editorial conventions | `wiki lint` | `wiki.yaml` → `lint:` | +| Link integrity | `wiki lint` | `wiki.yaml` → `lint:` | +| Dynamic SPARQL tables | `wiki render` | (query-driven; blocks are left untouched by fmt) | + +Recommended CI order: `fmt --check` → `lint --strict` → `check --strict` → `render --check`. + +## Usage + +```bash +wiki fmt +wiki fmt wiki/Some_Page.md +wiki fmt --check +wiki fmt -v +``` + +From another directory, pass the config path on the main command: + +```bash +wiki --config docs fmt -v +``` + +## Options + +| Flag | Description | +| ----------------- | ------------------------------------------------------------------------- | +| `FILE...` | Optional markdown paths; otherwise entire wiki | +| `--check` | Check formatting without modifying files; exits 1 if formatting is needed | +| `-v`, `--verbose` | Print fmt config source and formatted files | + +## Related + +- [Style Guide.md](Style_Guide.md) +- [wiki](wiki.md) +- [Wiki Configuration.md](Wiki_Configuration.md) diff --git a/docs/wiki/wiki_graph.md b/docs/wiki/wiki_graph.md new file mode 100644 index 0000000..f410fd6 --- /dev/null +++ b/docs/wiki/wiki_graph.md @@ -0,0 +1,57 @@ +--- +type: TechArticle +headline: wiki graph +description: List read-only RDF named graphs for root and installed source provenance. +--- + +# `wiki graph` + +Inspect read-only RDF named graph boundaries for a composed Wiki. + +## Usage + +```bash +wiki graph list +``` + +`wiki graph list` prints the root graph plus one graph for each installed source available from `wiki.lock` and the local `.wiki/sources/` cache. + +| Column | Meaning | +| ------------- | --------------------------------------------- | +| `name` | `root` or the source name | +| `kind` | `root` or `source` | +| `uri` | Named graph URI for SPARQL `GRAPH` clauses | +| `commit` | Short resolved commit for installed sources | +| `required_by` | Source dependency owners, or `root` if direct | + +## Query a source graph + +Use the listed URI with native SPARQL: + +```sparql +SELECT ?s ?name WHERE { + GRAPH { + ?s schema:name ?name . + } +} +``` + +Use `GRAPH ?g` to include provenance in results: + +```sparql +SELECT ?g ?s WHERE { + GRAPH ?g { + ?s a schema:Thing . + } +} +``` + +## Read-only boundary + +`wiki graph list` is discovery only. It does not install, update, remove, edit, or write back to source repositories. Writable source workflows and SPARQL Update are intentionally deferred. + +## Related + +- [wiki query](wiki_query.md) +- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) +- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) diff --git a/docs/wiki/wiki_init.md b/docs/wiki/wiki_init.md new file mode 100644 index 0000000..eac1e5c --- /dev/null +++ b/docs/wiki/wiki_init.md @@ -0,0 +1,83 @@ +--- +type: TechArticle +headline: wiki init +description: Scaffold wiki.yml and starter wiki pages interactively. +--- + +# `wiki init` + +Create a new wiki project in the **current directory**: `wiki.yml`, `README.md`, and starter files under `wiki/`. + +Does not use loaded Config; safe to run before a config exists. Init runs once per clean directory — if `wiki.yml`, `README.md`, or a non-empty `wiki/` already exist, use a new directory or remove those files before re-running. + +## Usage + +```bash +wiki init +wiki init --git +wiki init --repo wazootech/wiki +wiki init --graph-context-wiki https://example.org/mywiki/ --site-base-url /mywiki +``` + +## Config vs scaffold + +**Config flags** write keys into `wiki.yml` via the packaged template ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)). + +**Scaffold-only** effects copy files (`README.md`, `wiki/*.md`) or run `git init`. + +## Options + +| Flag | Description | `wiki.yml` key | +| -------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `--git` | Run `git init` after scaffolding | — | +| `--repo` | GitHub `owner/repo`; infer `graph.context.wiki` and `site.base_url` for GitHub Pages | `graph.context.wiki`, `site.base_url` (inferred) | +| `--graph-context-wiki` | Override `graph.context.wiki` (overrides `--repo` inference) | `graph.context.wiki` | +| `--site-base-url` | Override `site.base_url` (default `/wiki` or inferred from `--repo`) | `site.base_url` | +| `--site-url-style` | Override `site.url_style`: `dir` or `file` (default `dir`) | `site.url_style` | +| `--graph-content-predicate` | Override `graph.content_predicate` CURIE (e.g. `schema:articleBody`) | `graph.content_predicate` | +| `--link-style` | Override `link.style`: standard page links (`standard`) or wikilinks (`wikilink`) | `link.style` | +| `--wiki-inputs` | Override `wiki.inputs` list (can be specified multiple times, default `[wiki]`) | `wiki.inputs` | +| `--graph-base-iri` | Override `graph.base_iri` URI | `graph.base_iri` | +| `--graph-implicit-types` | Override `graph.implicit_types` (can be specified multiple times) | `graph.implicit_types` | +| `--graph-implicit-types-policy` | Override `graph.implicit_types_policy`: `fallback` or `append` | `graph.implicit_types_policy` | +| `--graph-include-file-extension` | Override `graph.include_file_extension` flag (defaults to `--no-graph-include-file-extension`) | `graph.include_file_extension` | + +## URL resolution + +When `--graph-context-wiki` is not passed, init resolves `graph.context.wiki` in this order: + +1. **`--repo`** — GitHub Pages project site: `https://{owner}.github.io/{repo}/` and `site.base_url: /{repo}` (accepts `owner/repo`, HTTPS, or SSH URLs). +1. **Git remote** — If `.git` already exists or `--git` was passed, parse `git remote get-url origin` when it points at GitHub. +1. **Interactive prompt** — **Custom wiki namespace IRI** (default `https://wiki.example.org/`). + +`--graph-context-wiki` always wins over `--repo` and remote detection. `--site-base-url` overrides the inferred path from `--repo`. + +Document subject IRIs default to `graph.context.wiki`. Set optional `graph.base_iri` in `wiki.yml` when auto-generated document IRIs must differ from the `wiki:` namespace (see [Wiki Configuration](Wiki_Configuration.md)). + +## Prompts + +When no flag or git remote supplies `graph.context.wiki`, init prompts once: + +1. **Custom wiki namespace IRI** (default `https://wiki.example.org/`) → `wiki:` in `graph.context` + +When the namespace came from that prompt, the prompt ends and initialization proceeds. + +Always includes `schema`, `wiki`, `wazoo`, `foaf`, `dc`, `dcterms`, `sh`, and `xsd` prefixes. The `wazoo` URI is fixed in the scaffold (`https://schema.wazoo.dev/`), like the other built-in prefixes. + +## Generated config + +New wiki projects receive a plain `wiki.yml` rendered from [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml). Jinja variables (such as `graph_context_wiki`, `site_base_url`, `graph_content_predicate`, and `link_style`) map from init CLI flags into nested blocks. + +For every key — schema default, whether init writes it, and which command audits it — see [Wiki Configuration → Overview](Wiki_Configuration.md#overview) and the per-block defaults tables in [Wiki Configuration](Wiki_Configuration.md). + +## Generated files + +- `README.md` — starter wiki overview and common commands +- `wiki/Person_Shape.md` — starter `sh:NodeShape` for `schema:Person` +- `wiki/Ethan_Davidson.md` — starter `schema:Person` example (includes a tweak comment to replace with your first page) + +## Related + +- [Getting Started](Getting_Started.md) +- [Wiki Configuration](Wiki_Configuration.md) +- [Wiki Page Layouts](Wiki_Page_Layouts.md) diff --git a/docs/wiki/wiki_install.md b/docs/wiki/wiki_install.md new file mode 100644 index 0000000..a769367 --- /dev/null +++ b/docs/wiki/wiki_install.md @@ -0,0 +1,45 @@ +--- +type: TechArticle +headline: wiki install +description: Fetch and lock external data sources declared in wiki.yml. +--- + +# `wiki install` + +Fetch external data sources (git repositories with wiki pages or RDF data), resolve commit SHAs, and pin them in `wiki.lock`. Without arguments, installs all sources declared in the `sources:` block of `wiki.yml`. With a URL, adds the source to `wiki.yml` first, then fetches and locks it. + +You can use GitHub `owner/repo` shorthand instead of a full URL — `EthanThatOneKid/solar-system-wiki` expands to `https://github.com/EthanThatOneKid/solar-system-wiki.git` automatically. + +**Transitive dependencies** are resolved recursively. `wiki install` reads each cloned source's own `wiki.yml` to discover its `sources:` block, fetches those transitive sources, and locks them too — forming a dependency tree. Circular dependency chains are detected and raise an error. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error. + +## Usage + +```bash +wiki install +wiki install https://github.com/EthanThatOneKid/solar-system-wiki.git +wiki install https://github.com/EthanThatOneKid/solar-system-wiki.git#v0.1.0 +wiki install EthanThatOneKid/solar-system-wiki +``` + +## Options + +| Flag | Description | +| ----- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `URL` | Git repository URL to add and install. Supports `#ref` pinning (branch, tag, or commit). If omitted, installs all sources from `wiki.yml`. | + +## Lockfile + +`wiki install` produces `wiki.lock` in the same directory as `wiki.yml`. This machine-authored JSON file records the resolved commit SHA, requested ref, and fetch timestamp for each source. Check it into version control so builds are reproducible — the lockfile is the source of truth for which version of each source is used. + +## Source cache + +Cloned repositories are cached under `.wiki/sources//repo/` relative to the wiki config root. `wiki install` always fetches the latest remote refs (shallow clone, `--depth 1`) so it stays fast. + +## `.gitignore` + +The `.wiki/` source cache directory (and the `_site/` build output) should not be committed to version control. `wiki init` scaffolds a `.gitignore` that includes both directories. + +## Related + +- [wiki remove](wiki_remove.md) +- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) diff --git a/docs/wiki/wiki_link.md b/docs/wiki/wiki_link.md new file mode 100644 index 0000000..00f2d6d --- /dev/null +++ b/docs/wiki/wiki_link.md @@ -0,0 +1,65 @@ +--- +type: TechArticle +headline: wiki link +description: Suggest missing wikilinks and repair unambiguous broken internal links. +--- + +# `wiki link` + +Suggest **missing wikilinks** for plain-text mentions of other wiki pages, or **repair** broken internal links when the fix is unambiguous. Report-only by default — mutations require explicit flags. + +## Usage + +```bash +wiki link +wiki link wiki/Some_Page.md +wiki link wiki/A.md wiki/B.md +wiki link -v +wiki link --check +wiki link --dry-run --apply +wiki link --apply +wiki link --fix-broken +wiki link --fix-broken --dry-run +``` + +## Options + +| Flag | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FILE...` | Optional markdown paths; otherwise entire wiki | +| `--apply` | Insert internal links for each suggestion (body only, never frontmatter); format from `link.style` in [wiki.yaml](Wiki_Configuration.md) (`standard` or `wikilink`) | +| `--fix-broken` | Repair unambiguous broken wikilinks and internal markdown page links | +| `-n`, `--dry-run` | Preview `--apply` or `--fix-broken` without writing files | +| `-c`, `--check` | Exit 1 if opportunities or broken links remain (CI gate) | +| `-v`, `--verbose` | Include target titles in report output; print changed files when applying | + +## Detection rules + +Missing-link suggestions skip: + +- Existing wikilinks and markdown links +- Fenced and inline code +- Self-links and overlapping aliases (longest alias wins) +- Short single-word acronyms (for example `HTML`, `JSON`) unless the page slug humanizes to the same text + +Broken-link repair (`--fix-broken`) only runs when: + +- The target page rename is listed in `link.renames` (see [Wiki Configuration](Wiki_Configuration.md)) +- A unique fuzzy route match exists among wiki pages +- A unique fuzzy heading fragment exists on the target page + +It never auto-creates pages or deletes links. Asset links, metadata CURIEs, and ambiguous matches stay manual. + +## Why not check or lint? + +- **`wiki lint`** is the convention lane — broken links, filename pattern, heading style, and link style. It reports but does not edit files; repair is `wiki link --fix-broken`. Missing wikilinks are optional enrichment, not a lint violation. +- **`wiki check`** is the integrity lane — SHACL, JSON Schema frontmatter, routes, collisions, layout frontmatter. It does not scan prose for broken links. +- **`wiki link`** requires explicit `--apply` or `--fix-broken` because suggestions are heuristic and repairs are conservative by design. +- See [Design Philosophies](Design_Philosophies.md#check-lint-fmt-and-link) for the full lane model. + +## Related + +- [wiki lint](wiki_lint.md) — convention lane (`lint.broken_links`) +- [wiki check](wiki_check.md) — integrity lane (SHACL, JSON Schema, routes, layout) +- [Style Guide](Style_Guide.md) — internal link conventions +- [wiki](wiki.md) diff --git a/docs/wiki/wiki_lint.md b/docs/wiki/wiki_lint.md new file mode 100644 index 0000000..b3e7376 --- /dev/null +++ b/docs/wiki/wiki_lint.md @@ -0,0 +1,72 @@ +--- +type: TechArticle +headline: wiki lint +description: Convention audits for broken links, filename patterns, heading style, and internal link style. +--- + +# `wiki lint` + +Run **convention** audits on the wiki: broken links, filename pattern, heading style, and internal link style. + +Exits **0 silently** on success unless `-v` is set. See [Design Philosophies](Design_Philosophies.md). + +## Usage + +```bash +wiki lint +wiki lint wiki/Some_Page.md +wiki lint wiki/A.md wiki/B.md +wiki lint -v +wiki lint --strict +``` + +## Options + +| Flag | Description | +| ----------------- | ---------------------------------------------- | +| `FILE...` | Optional markdown paths; otherwise entire wiki | +| `-v`, `--verbose` | Print warnings | +| `--strict` | Treat warnings as errors (exit 1) | + +## What is linted + +### Configurable (`lint.*` in `wiki.yaml`) + +| Rule key | What it audits | +| -------------------- | ------------------------------------------------------------------------------------------------ | +| `broken_links` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs | +| `filename_pattern` | Full filename vs `wiki.filename_pattern` regex (`.md` files only) | +| `headings` | Sentence-case H2+ (H1 title case conventional), numbered headings (ATX syntax is **`wiki fmt`**) | +| `heading_levels` | Heading depth must increase by one level at a time (MD001-inspired) | +| `duplicate_headings` | Duplicate H2+ heading text in the same document (MD024-inspired) | +| `thematic_breaks` | Horizontal rules (`---`, `***`, `___`) in body prose | +| `link_style` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` | + +Each rule is `error`, `warning`, or `off`. Defaults: `broken_links`, `filename_pattern`, and `link_style` are `warning`; `headings`, `heading_levels`, `duplicate_headings`, and `thematic_breaks` are `off`. + +`wiki lint` reports broken links only — it does not repair them. Use [wiki link](wiki_link.md) `--fix-broken` for unambiguous repairs (rename map, unique fuzzy slug, or heading match). + +Route safety errors (spaces, unsafe URL characters) abort lint with errors before convention rules run. + +### Single-file mode + +`wiki lint path/to/Page.md` runs broken-link, filename, heading, and link-style audits for that route only. + +## Related CI commands + +| Command | Purpose | +| --------------------- | ---------------------------------------------------------------- | +| `wiki fmt --check` | mdformat consistency (`fmt:` in wiki config or fallback TOML) | +| `wiki lint --strict` | Conventions (`lint:` in yaml) | +| `wiki check --strict` | SHACL, JSON Schema frontmatter, route safety, layout frontmatter | +| `wiki render --check` | Stale inline SPARQL result blocks | + +Run in that order in CI: `fmt`, then `lint`, then `check` — so mechanical fixes land before conventions and integrity checks. + +`wiki build` runs `wiki lint` then `wiki check` before writing output unless `--no-check`. + +## Related + +- [Wiki Configuration](Wiki_Configuration.md) — `lint.*` severities and config semantics +- [wiki check](wiki_check.md) — integrity lane +- [Style Guide](Style_Guide.md) diff --git a/docs/wiki/wiki_mcp.md b/docs/wiki/wiki_mcp.md new file mode 100644 index 0000000..6ca560e --- /dev/null +++ b/docs/wiki/wiki_mcp.md @@ -0,0 +1,145 @@ +--- +type: TechArticle +headline: wiki mcp +description: Run a read-only MCP server for querying the wiki graph. +--- + +# `wiki mcp` + +Start a local [Model Context Protocol](https://modelcontextprotocol.io/) server for the configured Wiki graph. The server is read-only and query-first: it exposes SPARQL execution and graph context for agents, not page editing, formatting, link repair, build, or filesystem automation. + +## Usage + +```bash +wiki mcp +wiki -c docs/wiki.yml mcp +wiki --wiki-inputs docs/wiki mcp +wiki mcp --mode stdio +wiki mcp --cache +``` + +`stdio` is the default and only transport in the first version. + +## Claude Code setup + +Register the local server with Claude Code: + +```bash +claude mcp add wiki -- wiki -c docs/wiki.yml mcp +``` + +Generic stdio MCP clients should run the same command shape: + +```bash +wiki -c docs/wiki.yml mcp +``` + +## Options + +| Flag | Default | Description | +| --------- | ------- | ------------------------------------------------------------ | +| `--mode` | `stdio` | MCP transport mode. | +| `--cache` | off | Persist graph artifacts under `.wiki/cache` across launches. | + +## Tools + +### `query_sparql` + +Execute SPARQL against the compiled wiki graph. + +Parameters: + +```json +{ + "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10", + "format": "json", + "inference": true, + "reload": false +} +``` + +Allowed query forms: `SELECT`, `ASK`, `CONSTRUCT`, and `DESCRIBE`. SPARQL Update and unsupported query forms are rejected before execution. + +`format` reuses [wiki query](wiki_query.md) names and aliases: `table`, `json`, `csv`, `tsv`, `turtle`, `n3`, and `markdown`. The MCP default is `json`. + +The tool returns a structured object: + +```json +{ + "format": "json", + "query_form": "SELECT", + "result": "..." +} +``` + +### `describe_wiki` + +Return factual context for writing grounded SPARQL: + +- Wiki CLI version +- Config path and inputs +- Namespace bindings from the built graph +- Graph stats for the default inferred graph +- Observed vocabulary from the graph + +The vocabulary summary is intentionally load-bearing for agent use. It lists real classes and predicates so agents can avoid inventing predicates, getting empty results, and treating a bad query as missing data. + +Example shape: + +```json +{ + "version": "0.1.21", + "config": "docs/wiki.yml", + "inputs": ["docs/wiki"], + "namespaces": { + "schema": "https://schema.org/", + "wiki": "https://wiki.example.org/" + }, + "graph": { + "triples": 1234, + "subjects": 120, + "predicates": 45, + "objects": 900, + "inference": true + }, + "vocabulary": { + "classes": [ + { "iri": "https://schema.org/Person", "curie": "schema:Person", "count": 12 } + ], + "predicates": [ + { "iri": "https://schema.org/name", "curie": "schema:name", "count": 42 } + ] + } +} +``` + +Vocabulary limits are intentionally compact: top 25 classes by `rdf:type` usage and top 50 predicates by triple count. + +## Resources + +| Resource | MIME type | Purpose | +| ------------------- | ------------------ | -------------------------------------------------------------- | +| `wiki://info` | `application/json` | Version, config, inputs, graph settings, stats, and vocabulary | +| `wiki://namespaces` | `application/json` | Prefix map for SPARQL authoring | +| `wiki://graph.ttl` | `text/turtle` | Current inferred graph serialized as Turtle | + +## Safety model + +`wiki mcp` is read-only by default: + +- No wiki source mutation +- No build output writes +- No formatting changes +- No link repair +- No generic file read/write tools +- No Obsidian automation +- No SPARQL Update + +The command reuses the same graph cache behavior as other Wiki CLI operations: in-process caching is always used within one running MCP server, and `--cache` enables filesystem persistence under `.wiki/cache` for faster reuse across MCP launches. `reload=true` on `query_sparql` rebuilds the in-memory graph before executing the query; with `--cache`, the rebuilt graph is also written back to the filesystem cache. + +## Related + +- [wiki query](wiki_query.md) +- [wiki serve](wiki_serve.md#sparql-endpoint) +- [Graph Cache](Graph_Cache.md) +- [SPARQL](SPARQL.md) diff --git a/docs/wiki/wiki_query.md b/docs/wiki/wiki_query.md new file mode 100644 index 0000000..683772e --- /dev/null +++ b/docs/wiki/wiki_query.md @@ -0,0 +1,89 @@ +--- +type: TechArticle +headline: wiki query +description: Run SPARQL SELECT or CONSTRUCT against the wiki graph. +--- + +# `wiki query` + +Execute **SPARQL** against the loaded wiki graph (with OWL-RL inference unless `--no-inference`). Unscoped queries read the union of root content and installed sources. Use native SPARQL `GRAPH` clauses when you need source boundaries. + +## Usage + +```bash +wiki query "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" +wiki query --pretty "SELECT ?given ?family WHERE { ?s schema:givenName ?given ; schema:familyName ?family }" +cat query.sparql | wiki query -f json +wiki query "SELECT ?given WHERE { ?s schema:givenName ?given }" --jq 'results.bindings[].given.value' +wiki query "..." --reload -v +wiki query "..." --cache +``` + +## Options + +| Flag | Description | +| ----------------- | ------------------------------------------------------------------------------ | +| `QUERY` | SPARQL string, or omit to read stdin | +| `-f`, `--format` | `table` (default), `json`, `csv`, `tsv`, `turtle`, `n3`, `markdown` | +| `-o`, `--output` | Write results to a file | +| `--pretty` | Rich table for SELECT results (stdout only; incompatible with `-o` and `--jq`) | +| `--no-inference` | Skip OWL-RL | +| `--reload` | Rebuild in-memory graph in this process | +| `--cache` | Persist a warm graph under `.wiki/cache/` for reuse across new processes | +| `--jq` | Filter JSON output (implies `-f json`) | +| `-v`, `--verbose` | Print triple/subject counts first | + +## Inspect one document + +Use `--pretty` with a subject-focused SELECT to peek at frontmatter triples in the terminal. Markdown body and typed infobox layout are not reproduced — use [wiki serve](wiki_serve.md) for full page preview. + +```bash +wiki query --pretty "SELECT ?property ?value WHERE { + wiki:Gregory_Davidson ?property ?value . +}" +``` + +## Graph reuse + +See [Graph Cache](Graph_Cache.md) — one graph per process unless `--reload`, plus optional cross-process warm-start via `--cache`. + +## Source provenance + +Installed sources are exposed as read-only RDF named graphs. Discover graph URIs with [wiki graph](wiki_graph.md): + +```bash +wiki graph list +``` + +Then scope a query with native SPARQL: + +```sparql +SELECT ?name WHERE { + GRAPH { + ?s schema:name ?name . + } +} +``` + +Or ask which graph supplied each binding: + +```sparql +SELECT ?g ?s WHERE { + GRAPH ?g { + ?s a schema:Thing . + } +} +``` + +This is read-only provenance. It does not mutate installed sources or implement SPARQL Update. + +## HTTP endpoint + +The same query engine backs an optional read-only SPARQL HTTP route when `sparql_service.enabled` is on in `wiki.yaml`. Configure keys and path collision rules in [Wiki Configuration](Wiki_Configuration.md#serve-api); request forms and `Accept` negotiation in [wiki serve](wiki_serve.md#sparql-endpoint). + +## Related + +- [SPARQL](SPARQL.md) +- [wiki graph](wiki_graph.md) +- [wiki render](wiki_render.md) +- [wiki serve](wiki_serve.md#sparql-endpoint) diff --git a/docs/wiki/wiki_remove.md b/docs/wiki/wiki_remove.md new file mode 100644 index 0000000..cae156c --- /dev/null +++ b/docs/wiki/wiki_remove.md @@ -0,0 +1,28 @@ +--- +type: TechArticle +headline: wiki remove +description: Remove a data source from wiki.yml, its cache, and wiki.lock. +--- + +# `wiki remove` + +Remove a previously installed source by name. Deletes the source entry from the `sources:` block in `wiki.yml`, removes the cached repository under `.wiki/sources//`, and deletes the entry from `wiki.lock`. + +**Transitive dependency cleanup:** when a source is removed, transitive sources that are no longer required by any remaining top-level source are automatically cleaned up — their cache and lockfile entries are removed too. + +## Usage + +```bash +wiki remove shared-taxonomy +``` + +## Arguments + +| Argument | Description | +| -------- | --------------------------------------------------------- | +| `name` | Name of the source to remove (as declared in `wiki.yml`). | + +## Related + +- [wiki install](wiki_install.md) +- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) diff --git a/docs/wiki/wiki_render.md b/docs/wiki/wiki_render.md new file mode 100644 index 0000000..a1a9f8f --- /dev/null +++ b/docs/wiki/wiki_render.md @@ -0,0 +1,164 @@ +--- +type: TechArticle +headline: wiki render +description: Update inline SPARQL result tables in markdown files. +--- + +# `wiki render` + +Find `<!-- sparql:start -->` ... `<!-- sparql:end -->` regions in markdown, run the embedded query against the wiki graph, and rewrite the table (or `(no results)`) in place. + +Silent on success by default. See [Design Philosophies](Design_Philosophies.md). + +## Usage + +```bash +wiki render +wiki render wiki/Report.md +wiki render wiki/people/alpha.md wiki/projects/beta.md +wiki render wiki/people/*.md +wiki render -v +wiki render --check +wiki render --no-inference +wiki render --reload +wiki render --cache +``` + +## Options + +| Flag | Description | +| ----------------- | -------------------------------------------------------------------------------------- | +| `FILE...` | Optional `.md` paths; otherwise entire wiki (shell globs expand to multiple FILE args) | +| `--check` | Dry-run; exit 1 if any block is stale | +| `--no-inference` | Skip OWL-RL | +| `--reload` | Rebuild graph before rendering | +| `--cache` | Persist a warm graph under `.wiki/cache/` for reuse across new processes | +| `-v`, `--verbose` | Print update counts | + +## Block format + +See [Style Guide](Style_Guide.md) for the `sparql:start` / `sparql:end` wrapper and fenced `sparql` code block. Close the start comment before the fence to show the query in built HTML. Leave it open and close after the fence to hide the query from published pages while `wiki render` still updates the table. + +## Examples + +### List all people (visible query) + +The default visible block style shows the query in published HTML so readers can see and learn from it. + + +```sparql +PREFIX rdf: +PREFIX schema: + +SELECT ?person ?givenName ?familyName WHERE { + ?person rdf:type schema:Person . + ?person schema:givenName ?givenName . + ?person schema:familyName ?familyName . +} +ORDER BY ?familyName +``` + +| person | givenName | familyName | +| --- | --- | --- | +| [Jeff_Kazzee](Jeff_Kazzee.md) | Jeff | Kazzee | +| https://wiki.example.org/people/Alice_Smith | Alice | Smith | + + +### List all software applications (hidden query) + +The hidden query style keeps the SPARQL inside an HTML comment — invisible in published pages, but still executed by `wiki render`. + + +| app | name | version | +| --- | --- | --- | +| [Linked_Markdown](Linked_Markdown.md) | Linked Markdown | | +| [Obsidian](Obsidian.md) | Obsidian | | +| [Vivary](Vivary.md) | Vivary | 0.1.0 | +| [wiki](wiki.md) | Wiki CLI | 0.1.21 | + + +### More query patterns + +Paste one of these SPARQL queries into a `sparql:start` block on any wiki page and run `wiki render` to see results. + +**All TechArticles with headlines and descriptions:** + +```sparql +PREFIX rdf: +PREFIX schema: + +SELECT ?headline ?description WHERE { + ?doc rdf:type schema:TechArticle . + ?doc schema:headline ?headline . + OPTIONAL { ?doc schema:description ?description . } +} +ORDER BY ?headline +``` + +**Full-text search for pages that mention a term in their body:** + +```sparql +PREFIX rdf: +PREFIX schema: + +SELECT ?headline WHERE { + ?doc rdf:type schema:TechArticle . + ?doc schema:headline ?headline . + ?doc schema:articleBody ?body . + FILTER(CONTAINS(?body, "your-search-term")) +} +ORDER BY ?headline +``` + +**Backlinks to a target page via body text:** + +```sparql +PREFIX rdf: +PREFIX schema: + +SELECT ?headline WHERE { + ?doc rdf:type schema:TechArticle . + ?doc schema:headline ?headline . + ?doc schema:articleBody ?body . + FILTER(CONTAINS(?body, "Target_Page")) +} +ORDER BY ?headline +``` + +Replace `"Target_Page"` with a page filename (without `.md`) to find pages that link to it. + +**Recent changes by date (requires date frontmatter):** + +Add `dateCreated` or `dateModified` to your page frontmatter with a YAML date (e.g. `dateCreated: 2026-06-28`). The wiki graph automatically types these as `xsd:date`. Then query: + +```sparql +PREFIX rdf: +PREFIX schema: + +SELECT ?headline ?created WHERE { + ?doc rdf:type schema:TechArticle . + ?doc schema:headline ?headline . + ?doc schema:dateCreated ?created . +} +ORDER BY DESC(?created) +``` + +## Related + +- [SPARQL](SPARQL.md) +- [Style Guide](Style_Guide.md) — `sparql:start` / `sparql:end` block format +- [Graph Cache](Graph_Cache.md) +- [wiki query](wiki_query.md) +- [wiki build](wiki_build.md) — `wiki build --render` diff --git a/docs/wiki/wiki_serve.md b/docs/wiki/wiki_serve.md new file mode 100644 index 0000000..2f36790 --- /dev/null +++ b/docs/wiki/wiki_serve.md @@ -0,0 +1,105 @@ +--- +type: TechArticle +headline: wiki serve +description: Local HTTP server for live HTML preview and optional read-only SPARQL endpoint. +--- + +# `wiki serve` + +Start a development server that renders wiki pages on demand. + +## Usage + +```bash +wiki serve +wiki serve --host 0.0.0.0 --port 3000 +wiki serve --watch +wiki serve --site-base-url /my-wiki --site-url-style dir +python -m wiki serve --watch +``` + +## Options + +| Flag | Default | Description | +| ------------------ | ----------- | ----------------------------------------------------------- | +| `--host` | `127.0.0.1` | Bind address | +| `--port` | `8080` | Port | +| `--site-base-url` | from config | Override `site.base_url` page URL prefix | +| `--site-url-style` | from config | Override `site.url_style`: `dir` or `file` | +| `--watch` | off | Rebuild graph, SPARQL blocks, and reload browser on changes | + +Default URL with config `site.base_url: /wiki`: `http://127.0.0.1:8080/wiki/`. + +## SPARQL endpoint + +When `sparql_service.enabled` is on, `wiki serve` also exposes a read-only SPARQL endpoint at `sparql_service.path` (default `/api/sparql`). See [Wiki Configuration](Wiki_Configuration.md#serve-api) for config keys, opt-in defaults, and path collision rules. + +A bare `GET` on that path (no query string) returns a [SPARQL 1.1 Service Description](https://www.w3.org/TR/sparql11-service-description/) document (OWL-RL as the default entailment profile, supported result formats, default dataset triple count when available). Content negotiation applies: `text/turtle`, `application/rdf+xml`, or `application/n-triples`. + +Example config: + +```yaml +sparql_service: + enabled: true + path: /api/sparql +``` + +### Supported query forms + +`SELECT`, `ASK`, `CONSTRUCT`, and `DESCRIBE` are accepted. SPARQL Update is rejected with `405`. + +### Request forms + +```bash +# Service description (SPARQL 1.1 Service Description) +curl "http://127.0.0.1:8080/api/sparql" -H "Accept: text/turtle" + +# GET with query string +curl "http://127.0.0.1:8080/api/sparql?query=SELECT%20*%20WHERE%20%7B%20?s%20?p%20?o%20%7D" \ + -H "Accept: application/sparql-results+json" + +# POST raw SPARQL query +curl "http://127.0.0.1:8080/api/sparql" \ + -H "Content-Type: application/sparql-query" \ + -H "Accept: text/turtle" \ + --data "CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }" + +# POST application/x-www-form-urlencoded (query= plus optional inference/reload) +curl "http://127.0.0.1:8080/api/sparql" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -H "Accept: application/sparql-results+json" \ + --data "query=ASK%20%7B%20%3Fs%20%3Fp%20%3Fo%20%7D" +``` + +Use the `Accept` header to choose the response serialization. Unsupported values return `406`. + +| Query form | Accepted `Accept` values | +| ----------------------- | ------------------------------------------------------------------------------------ | +| `SELECT`, `ASK` | `application/sparql-results+json` (default), `text/csv`, `text/tab-separated-values` | +| `CONSTRUCT`, `DESCRIBE` | `text/turtle` (default), `application/n-triples`, `text/n3` | + +Wiki-specific query parameters (GET query string, or form body on `application/x-www-form-urlencoded` POST): + +- `inference=true|false` — OWL-RL inference (default `true`; mirrors `wiki query` unless `--no-inference`) +- `reload=true|false` — rebuild the in-memory graph before executing (default `false`) + +The endpoint reuses the same query engine as [wiki query](wiki_query.md). + +For safety, the endpoint is **disabled by default**. Its path is validated at startup and rejected if it would shadow page routes or the `__watch` endpoint. + +## Wiki page layout + +The same `site.layout` from [Wiki Configuration](Wiki_Configuration.md#page-layout) applies to the dev server — a page layout (`.html`; packaged `index.html` when unset). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md). Page bodies use the same markdown renderer as `wiki build`; raw HTML in markdown is not emitted as live markup. + +## Metadata view + +The live page metadata panel supports RDF formats without JavaScript: compacted JSON-LD, Turtle, N3, RDF/XML, N-Triples, TriG, and N-Quads. A compact **Format** chip row selects the view. Set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). See [Content Negotiation](Content_Negotiation.md) for the HTTP `Accept` model. + +## Related + +- [wiki build](wiki_build.md) +- [wiki query](wiki_query.md) +- [SPARQL](SPARQL.md) +- [Graph Cache](Graph_Cache.md) +- [Wiki Configuration](Wiki_Configuration.md#serve-api) +- [Content Negotiation](Content_Negotiation.md) diff --git a/docs/wiki/wiki_update.md b/docs/wiki/wiki_update.md new file mode 100644 index 0000000..378f624 --- /dev/null +++ b/docs/wiki/wiki_update.md @@ -0,0 +1,39 @@ +--- +type: TechArticle +headline: wiki update +description: Check locked sources for newer commits and update wiki.lock. +--- + +# `wiki update` + +Fetch each locked source, resolve the current HEAD (or the configured ref), and compare against the pinned commit in `wiki.lock`. If the commit has changed, update the lockfile entry. + +This is the incremental counterpart to `wiki install` — it only writes the lockfile when something actually changed, and reports what updated. + +**Transitive dependency re-sync:** after updating commits, `wiki update` re-discovers each source's declared transitive dependencies. Newly declared sources are automatically installed and locked. Orphaned sources (transitive deps that were dropped by a source's new commit) are reported as warnings but not automatically removed — run `wiki remove ` to clean up. + +## Usage + +```bash +wiki update +wiki update solar-system +wiki update --dry-run +``` + +## Arguments + +| Argument | Description | +| -------- | ------------------------------------------------------- | +| `name` | Source name to check. Omit to check all locked sources. | + +## Options + +| Flag | Description | +| ----------------- | ----------------------------------------------------- | +| `-n`, `--dry-run` | Show what would update without modifying `wiki.lock`. | + +## Related + +- [wiki install](wiki_install.md) +- [wiki remove](wiki_remove.md) +- [Wiki Configuration](Wiki_Configuration.md#external-data-sources-sources) diff --git a/docs/wiki/wiki_upgrade.md b/docs/wiki/wiki_upgrade.md new file mode 100644 index 0000000..9d54b39 --- /dev/null +++ b/docs/wiki/wiki_upgrade.md @@ -0,0 +1,49 @@ +--- +type: TechArticle +headline: wiki upgrade +description: Check PyPI for updates and upgrade wazootech-wiki. +--- + +# `wiki upgrade` + +Compare the installed **wazootech-wiki** version to PyPI and optionally upgrade with pip. + +## Usage + +```bash +wiki upgrade -c # check only; exit 1 if outdated +wiki upgrade # prompt to upgrade when outdated +wiki upgrade -y # upgrade without prompt +wiki upgrade -y -v # show pip output +``` + +## Options + +| Flag | Description | +| ----------------- | ---------------------------------- | +| `-c`, `--check` | Report status only; do not install | +| `-y`, `--yes` | Skip confirmation | +| `-v`, `--verbose` | Show pip install logs | + +## Windows PATH troubleshooting + +If `python -m wiki upgrade` works but `wiki upgrade` says `No such command 'upgrade'`, PATH is probably resolving `wiki` to an older `wiki.exe` from a different Python install. + +Check which launcher is active: + +```powershell +Get-Command wiki +where.exe wiki +python -m wiki --help +``` + +If the PATH launcher is stale, upgrade through the intended interpreter and remove or refresh the older shim: + +```powershell +python -m wiki upgrade -y +python -m pip install --upgrade wazootech-wiki +``` + +## Related + +- [Getting Started](Getting_Started.md) diff --git a/scripts/release.py b/scripts/release.py index 2db0da7..de7b80a 100644 --- a/scripts/release.py +++ b/scripts/release.py @@ -18,11 +18,11 @@ import set_version ROOT = Path(__file__).resolve().parent.parent -DOCS_TO_FORMAT = ["docs/wiki/Wiki_CLI.md", "docs/wiki/Wiki_Subcommand_render.md"] +DOCS_TO_FORMAT = ["docs/wiki/wiki.md", "docs/wiki/wiki_render.md"] RELEASE_FILES = [ "CHANGELOG.md", - "docs/wiki/Wiki_CLI.md", - "docs/wiki/Wiki_Subcommand_render.md", + "docs/wiki/wiki.md", + "docs/wiki/wiki_render.md", "package-lock.json", "package.json", "pyproject.toml", diff --git a/scripts/set_version.py b/scripts/set_version.py index 8569b92..43db78b 100644 --- a/scripts/set_version.py +++ b/scripts/set_version.py @@ -56,13 +56,13 @@ def check_versions() -> dict[str, str]: if match: versions["src/wiki/__init__.py"] = match.group(1) - # 5. docs/wiki/Wiki_CLI.md - wiki_cli_path = root / "docs" / "wiki" / "Wiki_CLI.md" + # 5. docs/wiki/wiki.md + wiki_cli_path = root / "docs" / "wiki" / "wiki.md" if wiki_cli_path.exists(): content = wiki_cli_path.read_text(encoding="utf-8") match = re.search(r'(?m)^softwareVersion:\s*(\S+)', content) if match: - versions["docs/wiki/Wiki_CLI.md"] = match.group(1) + versions["docs/wiki/wiki.md"] = match.group(1) # 6. uv.lock uv_lock_path = root / "uv.lock" @@ -121,14 +121,14 @@ def update_versions(new_version: str) -> None: init_path.write_text(new_content, encoding="utf-8") print(f"Updated src/wiki/__init__.py -> {new_version}") - # 5. docs/wiki/Wiki_CLI.md - wiki_cli_path = root / "docs" / "wiki" / "Wiki_CLI.md" + # 5. docs/wiki/wiki.md + wiki_cli_path = root / "docs" / "wiki" / "wiki.md" if wiki_cli_path.exists(): content = wiki_cli_path.read_text(encoding="utf-8") new_content, count = re.subn(r'(?m)^softwareVersion:\s*\S+', f'softwareVersion: {new_version}', content) if count > 0: wiki_cli_path.write_text(new_content, encoding="utf-8") - print(f"Updated docs/wiki/Wiki_CLI.md -> {new_version}") + print(f"Updated docs/wiki/wiki.md -> {new_version}") # 6. uv.lock uv_lock_path = root / "uv.lock" diff --git a/tests/test_audit.py b/tests/test_audit.py index 39aaed5..aa79242 100644 --- a/tests/test_audit.py +++ b/tests/test_audit.py @@ -69,7 +69,7 @@ def test_audit_broken_wiki_curie_in_frontmatter(self) -> None: """Frontmatter wiki: CURIEs must resolve to an existing document route.""" with TemporaryDirectory() as tmpdir: config = Config(wiki={"inputs": [tmpdir]}) - Path(tmpdir, "Wiki_CLI.md").write_text("---\ntype: SoftwareApplication\n---\n", encoding="utf-8") + Path(tmpdir, "wiki.md").write_text("---\ntype: SoftwareApplication\n---\n", encoding="utf-8") Path(tmpdir, "Farzapedia.md").write_text( "---\ntype: TechArticle\nabout: wiki:wiki-cli\n---\n", encoding="utf-8", @@ -364,7 +364,7 @@ def test_lint_headings_ignores_capitalized_link_text_in_headings(self) -> None: config = Config(wiki={"inputs": [tmpdir]}) Path(tmpdir, "Compare.md").write_text( "---\ntype: TechArticle\n---\n" - "## Comparison with [Wiki CLI](Wiki_CLI.md) and [Letta MemFS](Letta_MemFS.md)\n", + "## Comparison with [Wiki CLI](wiki.md) and [Letta MemFS](Letta_MemFS.md)\n", encoding="utf-8", ) warnings = lint_headings(config) diff --git a/tests/test_cli.py b/tests/test_cli.py index 7f7ec0d..aa8a50c 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1643,7 +1643,7 @@ def test_cli_link_apply_and_check(self) -> None: with TemporaryDirectory() as tmpdir: wiki_dir = Path(tmpdir) / "wiki" wiki_dir.mkdir() - (wiki_dir / "Wiki_CLI.md").write_text("# Wiki CLI\n", encoding="utf-8") + (wiki_dir / "wiki.md").write_text("# Wiki CLI\n", encoding="utf-8") guide = wiki_dir / "Guide.md" guide.write_text("# Guide\n\nRead the Wiki CLI guide.\n", encoding="utf-8") @@ -1653,7 +1653,7 @@ def test_cli_link_apply_and_check(self) -> None: apply_result = runner.invoke(main, ["--wiki-inputs", str(wiki_dir), "link", "--apply"]) self.assertEqual(apply_result.exit_code, 0) - self.assertIn("[Wiki CLI](Wiki_CLI.md)", guide.read_text(encoding="utf-8")) + self.assertIn("[Wiki CLI](wiki.md)", guide.read_text(encoding="utf-8")) clean = runner.invoke(main, ["--wiki-inputs", str(wiki_dir), "link", "--check"]) self.assertEqual(clean.exit_code, 0) diff --git a/tests/test_format.py b/tests/test_format.py index 5409d6a..4250a3f 100644 --- a/tests/test_format.py +++ b/tests/test_format.py @@ -98,7 +98,7 @@ def test_compacted_json_ld_context_includes_only_used_prefixes(self) -> None: } compacted = process_rdf_format( frontmatter, - "Wiki_Subcommand_query", + "wiki_query", config.context, "json-ld", mode="compacted", diff --git a/tests/test_link_suggest.py b/tests/test_link_suggest.py index 23a6489..63be9c1 100644 --- a/tests/test_link_suggest.py +++ b/tests/test_link_suggest.py @@ -13,7 +13,7 @@ def test_finds_plain_text_mention_of_another_page(self) -> None: root = Path(tmpdir) wiki = root / "wiki" wiki.mkdir() - (wiki / "Wiki_CLI.md").write_text("# Wiki CLI\n", encoding="utf-8") + (wiki / "wiki.md").write_text("# Wiki CLI\n", encoding="utf-8") (wiki / "Getting_Started.md").write_text( "# Getting started\n\nRead the Wiki CLI guide before you begin.\n", encoding="utf-8", @@ -25,7 +25,7 @@ def test_finds_plain_text_mention_of_another_page(self) -> None: self.assertEqual(len(opportunities), 1) item = opportunities[0] self.assertEqual(item.source_route, "Getting_Started") - self.assertEqual(item.target_route, "Wiki_CLI") + self.assertEqual(item.target_route, "wiki") self.assertEqual(item.matched_text, "Wiki CLI") def test_skips_existing_wikilinks_and_code(self) -> None: @@ -33,7 +33,7 @@ def test_skips_existing_wikilinks_and_code(self) -> None: root = Path(tmpdir) wiki = root / "wiki" wiki.mkdir() - (wiki / "Wiki_CLI.md").write_text("# Wiki CLI\n", encoding="utf-8") + (wiki / "wiki.md").write_text("# Wiki CLI\n", encoding="utf-8") (wiki / "Guide.md").write_text( "# Guide\n\nAlready linked [[Wiki_CLI]] and literal `Wiki CLI` in code.\n", encoding="utf-8", @@ -84,7 +84,7 @@ def test_apply_inserts_markdown_links_by_default(self) -> None: root = Path(tmpdir) wiki = root / "wiki" wiki.mkdir() - (wiki / "Wiki_CLI.md").write_text("# Wiki CLI\n", encoding="utf-8") + (wiki / "wiki.md").write_text("# Wiki CLI\n", encoding="utf-8") guide = wiki / "Getting_Started.md" guide.write_text( "# Getting started\n\nRead the Wiki CLI guide before you begin.\n", @@ -96,7 +96,7 @@ def test_apply_inserts_markdown_links_by_default(self) -> None: changed = apply_link_opportunities(config, opportunities, dry_run=False) self.assertEqual(changed, [guide]) - self.assertIn("[Wiki CLI](Wiki_CLI.md)", guide.read_text(encoding="utf-8")) + self.assertIn("[Wiki CLI](wiki.md)", guide.read_text(encoding="utf-8")) self.assertEqual(find_link_opportunities(config), []) self.assertEqual(lint_broken_links(config), []) @@ -105,7 +105,7 @@ def test_apply_respects_frontmatter(self) -> None: root = Path(tmpdir) wiki = root / "wiki" wiki.mkdir() - (wiki / "Wiki_CLI.md").write_text("# Wiki CLI\n", encoding="utf-8") + (wiki / "wiki.md").write_text("# Wiki CLI\n", encoding="utf-8") page = wiki / "Guide.md" page.write_text( "---\ntype: TechArticle\n---\n\nInstall the Wiki CLI first.\n", @@ -117,14 +117,14 @@ def test_apply_respects_frontmatter(self) -> None: content = page.read_text(encoding="utf-8") self.assertTrue(content.startswith("---\ntype: TechArticle\n---\n\n")) - self.assertIn("[Wiki CLI](Wiki_CLI.md)", content) + self.assertIn("[Wiki CLI](wiki.md)", content) def test_apply_uses_wikilinks_when_link_style_configured(self) -> None: with TemporaryDirectory() as tmpdir: root = Path(tmpdir) wiki = root / "wiki" wiki.mkdir() - (wiki / "Wiki_CLI.md").write_text("# Wiki CLI\n", encoding="utf-8") + (wiki / "wiki.md").write_text("# Wiki CLI\n", encoding="utf-8") guide = wiki / "Getting_Started.md" guide.write_text( "# Getting started\n\nRead the Wiki CLI guide before you begin.\n", @@ -135,7 +135,7 @@ def test_apply_uses_wikilinks_when_link_style_configured(self) -> None: opportunities = find_link_opportunities(config) apply_link_opportunities(config, opportunities, dry_run=False) - self.assertIn("[[Wiki_CLI|Wiki CLI]]", guide.read_text(encoding="utf-8")) + self.assertIn("[[wiki|Wiki CLI]]", guide.read_text(encoding="utf-8")) if __name__ == "__main__": diff --git a/tests/test_site.py b/tests/test_site.py index d0a4c44..dc590ae 100644 --- a/tests/test_site.py +++ b/tests/test_site.py @@ -476,10 +476,10 @@ def test_markdown_links_leave_wiki_curie_as_route_text(self) -> None: encoding="utf-8", ) (wiki / "Farzapedia.md").write_text( - "---\ntype: TechArticle\nheadline: Farzapedia\nabout: wiki:Wiki_CLI\n---\n\n[Wiki CLI](wiki:Wiki_CLI)\n", + "---\ntype: TechArticle\nheadline: Farzapedia\nabout: wiki:wiki\n---\n\n[wiki](wiki:wiki)\n", encoding="utf-8", ) - (wiki / "Wiki_CLI.md").write_text( + (wiki / "wiki.md").write_text( "---\ntype: TechArticle\nname: Wiki CLI\n---\n\n# Wiki CLI\n", encoding="utf-8", ) @@ -487,8 +487,8 @@ def test_markdown_links_leave_wiki_curie_as_route_text(self) -> None: site = build_site(config, base_url="/wiki", url_style="dir") page = next(p for p in site.pages if p.full_slug == "Farzapedia") html = build_page_html(page, root, base_url="/wiki", url_style="dir", default_layout=_full_test_layout(root)) - self.assertIn('href="/wiki/wiki%3AWiki_CLI/"', html) - self.assertIn(">Wiki CLI", html) + self.assertIn('href="/wiki/wiki%3Awiki/"', html) + self.assertIn(">wiki", html) def test_fallback_article_uses_minimal_template(self) -> None: with TemporaryDirectory() as tmpdir: @@ -513,7 +513,7 @@ def test_default_layout_read_view_includes_first_heading(self) -> None: root = Path(tmpdir) wiki = root / "wiki" wiki.mkdir() - (wiki / "Wiki_CLI.md").write_text( + (wiki / "wiki.md").write_text( "---\ntype: schema:SoftwareApplication\nname: Wiki CLI\n---\n\n" "# Wiki CLI\n\nLead paragraph.\n", encoding="utf-8", diff --git a/tests/test_version.py b/tests/test_version.py index 86ce3b9..9b89931 100644 --- a/tests/test_version.py +++ b/tests/test_version.py @@ -12,7 +12,7 @@ class TestVersionSync(unittest.TestCase): def test_version_strings_are_in_sync(self) -> None: """Verify that all version strings across pyproject.toml, package.json, package-lock.json, - src/wiki/__init__.py, and docs/wiki/Wiki_CLI.md are identical. + src/wiki/__init__.py, and docs/wiki/wiki.md are identical. """ versions = set_version.check_versions() self.assertTrue(len(versions) > 0, "No version strings were parsed from the codebase.")