Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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<VERSION>` (e.g., `v0.1.18`).
Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
9 changes: 9 additions & 0 deletions docs/build.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
12 changes: 12 additions & 0 deletions docs/layouts/redirect.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="0; url=%wiki.redirect_url%">
<link rel="canonical" href="%wiki.redirect_url%">
<title>Redirecting...</title>
</head>
<body>
<p>Redirecting to <a href="%wiki.redirect_url%">%wiki.redirect_url%</a>...</p>
</body>
</html>
21 changes: 19 additions & 2 deletions docs/wiki.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -82,3 +98,4 @@ fmt:

# Pointer mode (optional TOML file relative to this file):
# fmt: .mdformat.toml

10 changes: 5 additions & 5 deletions docs/wiki/Agent_Memory_Filesystems.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand All @@ -29,15 +29,15 @@ 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.

**[Letta MemFS](Letta_MemFS.md)** — You build on **Letta Code** and want **Git history, human-editable memory, and a fixed always-on `system/` slice** for persona and project facts, with everything else progressively disclosed.

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

Expand Down
4 changes: 2 additions & 2 deletions docs/wiki/CSV.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 5 additions & 5 deletions docs/wiki/Content_Negotiation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions docs/wiki/Dataview_Integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
```
6 changes: 3 additions & 3 deletions docs/wiki/Declarative_Knowledge.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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)
2 changes: 1 addition & 1 deletion docs/wiki/Deploying_to_GitHub_Pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading