wiki-spaces 0.1.0__tar.gz

wiki_spaces-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.uv-cache/
+dist/
+build/
+.DS_Store
+*.swp
+.idea/
+.vscode/

wiki_spaces-0.1.0/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md
+
+The wiki-spaces spec. Vocabulary, structure, and the operating contract for an LLM working in a wiki-spaces wiki.
+
+## What a wiki is
+
+A wiki is a folder with `index.md`. That's it.
+
+You can stop here — a folder, an `index.md`, and whatever files you want is a complete wiki. The rest of this doc describes what's *possible* on top of that, not what's required.
+
+## Vocabulary
+
+A **space** is a folder with `index.md`. The unit, the building block.
+
+A **wiki** is a space — the one at the top of your tree, the one that's yours. From your perspective, it's "the wiki." Embedded in someone else's wiki via clone / submodule / symlink, it's just a space inside theirs. The word changes with position; the thing doesn't.
+
+Inside a space, three kinds of inhabitant:
+
+- **Files** — leaf content (markdown, images, data, anything).
+- **Folders** — plain folders (no `index.md`), used for grouping without first-class status (assets, drafts, attachments, raw payloads).
+- **Spaces** — folders that themselves have `index.md`, recursively.
+
+Zero contained spaces is a fine wiki. Deep nesting is a fine wiki. Your shape is your call.
+
+## Tiers
+
+Three tiers of opt-in. Each tier adds capability and the small contract tools rely on *at that tier*. A wiki opts in by adding the marker; tools detect the tier from what's present and degrade where it isn't. Pick the highest tier that fits your needs.
+
+### Tier 1 — Valid
+
+A folder with `index.md`. Tools can find the wiki, read its `index.md`, and operate on the files within. No structural promises beyond "I'm a wiki." Search uses filesystem globs since there's no curated map.
+
+### Tier 2 — Navigable
+
+`index.md` grows three sections so the wiki maps itself:
+
+- **`## What this space is`** — opening paragraph in plain prose. The space's own description.
+- **`## Items`** — curated list of files (and plain folders) worth surfacing. Not exhaustive; tools that need every file glob the filesystem.
+- **`## Spaces`** — every space directly inside this one, listed once. **Contract:** this list is exhaustive. Adding a space inside means adding it here in the same change; removing a space means removing the entry. Tools traverse via this list and rely on it being complete.
+
+The opt-in marker is the presence of `## Spaces`. When the marker is present, the contract holds: tools enforce exhaustiveness on writes (add/remove entries automatically) and flag missing entries on audit. When the marker is absent, the wiki is still valid — tools just don't navigate beyond the root `index.md`.
+
+Each space chooses its own tier independently. A wiki at Tier 2 may contain a space at Tier 1 and another at Tier 3.
+
+Cross-space references go horizontal: `[label](relative/path.md)` or `[[wikilink]]` if surrounding tooling supports it. `index.md` handles parent ↔ child navigation only.
+
+### Tier 3 — Managed
+
+Adopts the conventions catalog ([`CONVENTIONS.md`](CONVENTIONS.md)): `log.md`, `_meta/taxonomy.md`, `.manifest.json`, frontmatter schema, the categorical layout, optional `_template.md` and `hot.md`. The three reference skills (`wiki-search`, `wiki-update`, `wiki-tend`) can then fully exercise audit, normalize, cross-link, sync, log, and graph operations.
+
+Each marker is independent — adopt only what you want. `CONVENTIONS.md` describes what each one enables.
+
+## Sharing & nesting
+
+Sharing a wiki is sharing its folder. The receiver mounts it however they prefer — subdir, symlink, git submodule, clone, any filesystem mechanism. From their perspective, your wiki becomes a space inside theirs. The same applies at any level: a single space can be extracted and shared, and it lands in the receiver's tree as a space.
+
+**Trust scope.** Tools distinguish *owned* spaces (the wiki itself and spaces the user created inside it) from *external* spaces (mounts the user doesn't own — by convention, anything under `<wiki>/shared/`, any git submodule pointing at a foreign origin, or any symlink whose realpath resolves outside the wiki tree).
+
+- **Read operations** (search, audit, status) cross owned spaces by default. External spaces are visited only when the user explicitly names one or asks to include all.
+- **Write operations** stay within the targeted space by default. Other spaces — owned or external — are written to only with explicit instruction.
+
+This makes "audit my wiki" reach project knowledge in `projects/<name>/` automatically (those are yours), while leaving a teammate's wiki at `shared/team-foo/` untouched until you ask for it explicitly.
+
+## Outside the spec
+
+No frontmatter, no required tags, no fixed top-level categories, no required content schema, no special files beyond `index.md`. Folder names come from your domain — `clients/`, `papers/`, `projects/`, `recipes/`, `drafts/`, `journal/`, whatever fits. The spec doesn't care what your wiki is for. Anything else you see is convention or tooling, layered on top — see [`CONVENTIONS.md`](CONVENTIONS.md).

wiki_spaces-0.1.0/CONVENTIONS.md

@@ -0,0 +1,359 @@
+# Conventions
+
+This is the opt-in catalog. Every section is independent. The [spec](AGENTS.md) defines three tiers — Valid (just `index.md`), Navigable (adds `## Items` and `## Spaces`), and Managed (everything below). This catalog is the Managed tier: the markers tools detect by file presence to enable each convention. Adopt only what you want; tools degrade where a marker is absent.
+
+Wiki-syntax facts (wikilinks, frontmatter parsing, callouts, embeds, base views) are NOT redocumented here. They live in [`vendor/kepano/obsidian-markdown`](vendor/kepano/obsidian-markdown/SKILL.md) and [`vendor/kepano/obsidian-bases`](vendor/kepano/obsidian-bases/SKILL.md). Cite those skills, never restate their contents.
+
+---
+
+## Recommended Standard Pack
+
+A new wiki only needs `index.md` (per spec) to be valid. Beyond that, the "Standard Pack" varies by use case — it's whatever set of opt-in markers makes the reference skills useful for your wiki. Example packs:
+
+| Use case | Pack |
+|---|---|
+| Developer notebook | `log.md` + `_meta/taxonomy.md` + `.manifest.json` |
+| Research wiki | `log.md` + `_meta/taxonomy.md` |
+| Writing project | `hot.md` |
+| Recipe collection | (none — pure content) |
+| Personal knowledge | (none — pure content) |
+| Team reference | `log.md` + `_meta/taxonomy.md` |
+
+Each opt-in is independent — adopt any combination. Frontmatter (see § Frontmatter schema) is per-page rather than a pack file; mixed adoption is permitted. The catalog below explains what each marker enables; skip any of them and the corresponding tooling step degrades. The scaffold command takes any subset: `wiki-spaces init <path> --with log.md _meta/taxonomy.md` (prefix with `uvx` for no-install runs).
+
+---
+
+## Discovery via config
+
+Skills locate the user's canonical wiki by reading `${XDG_CONFIG_HOME:-~/.config}/wiki-spaces/config`. Plain text, key = value, blank lines ignored; whole-line comments start with `#`. Inline `#` is not a comment marker — paths may legitimately contain `#`, so keep comments on their own lines:
+
+```
+# wiki-spaces config
+# wiki: canonical wiki path (must contain index.md)
+# repo: path to wiki-spaces install (share dir from `wiki-spaces install`, or source checkout)
+wiki = /home/you/Wiki
+repo = /home/you/.local/share/wiki-spaces
+```
+
+Both keys are absolute paths. `wiki` points to a folder containing `index.md`; `repo` points to the wiki-spaces install — the share dir written by `wiki-spaces install` (PyPI users) or a source checkout (dev users) — so skills can fetch `AGENTS.md`, `CONVENTIONS.md`, and `references/` on demand. If either path doesn't resolve, skills fail soft and tell the user what's missing.
+
+**One canonical wiki per user.** wiki-spaces is built around a single wiki you call yours; the tooling assumes that. Users who want to switch between multiple wikis can swap configs manually. The single-wiki model is what makes global capture, cross-linking, and "open in Obsidian" all work coherently.
+
+Bootstrap: `wiki-spaces install` writes the `repo` key automatically; `wiki-spaces init` writes the `wiki` key when scaffolding (unless `--no-config`). If the config is missing or `wiki` is unset:
+- `wiki-update` runs the Initialization flow (see `wiki-update/SKILL.md` § Initialization, which mirrors `references/SETUP.md`).
+- `wiki-search` and `wiki-tend` fail soft: tell the user setup is needed and point them at `references/SETUP.md` (use the raw GitHub URL if the `repo` path is also unknown).
+
+CWD is a placement *hint*, never the discovery mechanism. The agent uses CWD and conversation context to decide *where in the wiki* a write goes (e.g., a project space vs global concepts), but the wiki itself is always the one in the config.
+
+## Per-space convention auto-detection
+
+Each space is autonomous: optional conventions (frontmatter, `_meta/taxonomy.md`, `log.md`, etc.) are detected by file presence *within that space*. Parent conventions do not propagate to children. Each space picks its own tier independently — a Tier 3 root may contain a Tier 1 space and vice versa.
+
+**Scope-root operations.** When a tool operates on a specific space (the wiki, or a space the user named), every convention check happens at *that scope's root* — not at an ancestor. The `log.md` appended to is the one at the scope being operated on. The taxonomy enforced is the one at that scope. The `.manifest.json` consulted is that scope's. Skip the marker at that scope and the corresponding step degrades for that scope only.
+
+## Owned vs external
+
+Per [`AGENTS.md / Sharing & nesting`](AGENTS.md#sharing--nesting), tools distinguish *owned* spaces (yours) from *external* spaces (mounts you don't own). Detection heuristic, in order:
+
+1. Path is under `<wiki>/shared/` → external.
+2. Path is a git submodule (in `.gitmodules`) whose origin URL doesn't match the wiki's own origin → external.
+3. Path is a symlink whose realpath resolves outside the wiki tree → external.
+4. Otherwise → owned.
+
+**Read operations** (search, status, audit) cross owned spaces by default. External spaces are visited only when the user explicitly names one or asks to include all.
+
+**Write operations** stay within the targeted space. Other spaces — owned or external — are written to only with explicit instruction.
+
+**Traversal safeguards** (when crossing into other spaces):
+- Track visited realpaths (resolve symlinks) to break cycles.
+- Skip broken symlinks and uninitialized git submodules with a one-line notice; don't error out on them.
+- Refuse `..` traversal above the wiki root. External spaces reached through a legitimate `## Spaces` entry ARE in scope when the user opts in — the prohibition is on ascending lexically, not on cross-mount realpaths.
+
+---
+
+## Sharing & permissions
+
+For shared or collaborative spaces, the recommended mechanism is **git repositories**. Each shared space is its own git repo; embed it in a parent via git submodule, clone, or symlink (see [`AGENTS.md` / Sharing & nesting](AGENTS.md#sharing--nesting) — all FS mechanisms remain valid; this section recommends one).
+
+**Two-gate write protection.** Tools should avoid accidental out-of-scope writes; sharing-aware tools should preflight ownership before mutating git-backed spaces they don't own.
+
+1. **First gate (always on).** The trust scope clause in [`AGENTS.md`](AGENTS.md#sharing--nesting) defaults *write operations* to the targeted space only. Other spaces — owned or external — are written to only when the user's request explicitly includes them (naming a space, asking for all, or any clear instruction). Read operations follow their own rule: they cross owned spaces by default; external spaces require opt-in. Both rules are scope-based, not ownership-based — and together form the primary safety net.
+
+2. **Second gate (only if backed by git).** Push access on the remote is the de facto upstream-publication permission. Without push access, local commits succeed but `git push` fails — changes never reach collaborators. This is a publication backstop, not a write-time check.
+
+**Honest caveat.** Push-as-permissions is a *late* check: local commits succeed; only the push fails. For agent-driven workflows this can surprise the user hours later. Always rely on the trust scope (gate #1) as the primary protection; treat push permissions as the safety net.
+
+**For local-only or private wikis,** git is not required. A folder with `index.md` is a complete wiki. Add git when you decide to share or back up.
+
+**Submodules.** When nesting shared spaces as git submodules:
+- Cloners need `git clone --recursive` (or `git submodule update --init` after a plain clone). Mention this in your wiki's `index.md` if you use them.
+- Submodules pin a SHA; the parent sees the pinned version until `git submodule update --remote` advances the working tree.
+- After advancing, the new SHA is only local until you commit the parent repo's updated submodule pointer (gitlink) and push.
+- GitHub release ZIPs do NOT include submodule contents.
+
+---
+
+## `index.md`
+
+**If present:** This folder is a space (per the [spec](AGENTS.md)). `index.md` typically grows three sections as the space grows:
+
+- **`## What this space is`** — opening paragraph, plain prose. The space's own description; preserved across regenerations.
+- **`## Items`** — curated human navigation. A hand-picked list of files and plain folders worth surfacing — not exhaustive. Tools that need every file glob the filesystem.
+- **`## Spaces`** — the navigation map: every space directly inside this one, listed once. The convention: the parent owns the link entry, the child owns its content. Adding a space inside means adding an entry here in the same change; removing a space means removing the entry. Tools rely on `## Spaces` being complete to traverse the tree.
+
+Entries in `## Items` and `## Spaces` are markdown bullet lists, one per line. Order is the author's choice (typically navigational, not alphabetical):
+
+- `## Items` — `[label](relative/path)` or `[[wikilink]]`, with an optional ` — short description`. Files and plain folders (folders without their own `index.md`) both belong here when worth surfacing. Hidden control files (`.manifest.json`, `_meta/...`, `_template.md`) are conventionally omitted unless a human reader needs to navigate to them.
+- `## Spaces` — `[label](sub-folder/index.md)`, with an optional ` — short description`.
+
+`## Items` is curated, so tools don't auto-add entries (only remove ones pointing to deleted files). `## Spaces` is meant to be exhaustive, so tools may flag sub-folders with `index.md` that aren't listed.
+
+Skip any of these sections and `index.md` still marks the folder as a wiki. Tools that lean on the convention degrade where it isn't followed — your wiki is still your wiki.
+
+**If absent:** This folder is not a wiki. Tools refuse to operate.
+
+---
+
+## `log.md`
+
+**If present:** Tools append one line per operation. Format:
+
+```
+- [TIMESTAMP] OPERATION key=value key=value
+```
+
+`TIMESTAMP` is UTC ISO-8601. `OPERATION` is uppercase verb (`SEARCH`, `UPDATE`, `TEND`). Keys are operation-specific.
+
+**If absent:** Tools skip logging. No log file is created automatically; create it (or run `wiki-spaces init <path> --with log.md`) to opt in.
+
+---
+
+## `hot.md`
+
+**If present:** Free-form scratchpad for current active work. Tools may read it for context (e.g., `wiki-search` may surface its mentions) but never rewrite it. Users own its content.
+
+**If absent:** Tools ignore. No proxy file is created.
+
+---
+
+## `.manifest.json`
+
+**If present:** Project sync state. Schema:
+
+```json
+{
+  "projects": {
+    "<project-slug>": {
+      "source_cwd": "/abs/path/to/source/repo",
+      "last_synced": "2026-05-14T10:30:00Z",
+      "last_commit_synced": "abc123",
+      "pages_in_vault": 12
+    }
+  }
+}
+```
+
+`last_commit_synced` is `null` when the source has no git. `wiki-update` reads it to skip unchanged sources and writes it after each sync.
+
+**If malformed:** Tools warn once, treat the file as absent for this run, and refuse to overwrite it until the user repairs or removes it.
+
+**If absent:** `wiki-update` performs a full scan on every sync. No project tracking.
+
+---
+
+## `_meta/taxonomy.md`
+
+**If present:** Canonical tag vocabulary. Applies to YAML frontmatter `tags:` fields. `wiki-tend` normalizes those to the canonical list, suggests adding genuinely new tags that appear on 2+ pages, and rejects unknown one-off tags with a closest-match suggestion. `wiki-update` consults it before assigning tags. Inline `#tag` syntax outside frontmatter is not normalized.
+
+Document shape:
+
+```markdown
+# Tag Taxonomy
+
+Constraints: max 5 tags per page, lowercase/hyphenated.
+
+## Domain Tags
+
+| Tag | Purpose | Aliases |
+|---|---|---|
+| `python` | Python language, ecosystem | |
+...
+
+## Type Tags
+
+| Tag | Purpose |
+|---|---|
+| `how-to` | Step-by-step procedure |
+...
+```
+
+Aliases are mappings the normalizer uses to rewrite non-canonical tags to canonical form.
+
+**If absent:** Tags are free-form. `wiki-tend` skips tag normalization with a notice; `wiki-update` does not enforce a vocabulary.
+
+---
+
+## `_template.md`
+
+**If present in any folder:** New pages created by `wiki-update` in that folder use this file as their boilerplate (frontmatter + body skeleton). The closest ancestor `_template.md` wins.
+
+**If absent:** New pages are created from the section "Page template" below if frontmatter is in use, otherwise as bare markdown.
+
+---
+
+## Frontmatter schema
+
+**If used (any content page in the wiki has YAML frontmatter):** The opt-in schema is:
+
+```yaml
+---
+title: >-
+  Page Title
+category: <one of your categorical layout values>
+tags: [tag1, tag2]
+aliases: [alternate-name]        # optional
+sources: [project-name, url]
+summary: >-
+  ≤200 chars; enough to decide whether to open the page.
+created: 2026-05-14T00:00:00Z
+updated: 2026-05-14T00:00:00Z
+---
+```
+
+Timestamps are UTC ISO-8601. `>-` folded scalar avoids YAML quoting issues for `title` and `summary`. Frontmatter syntax is owned by [obsidian-markdown](vendor/kepano/obsidian-markdown/SKILL.md).
+
+**Mixed adoption is allowed.** A wiki may have some content pages with frontmatter and some without; the convention is per-page, not per-wiki. `wiki-tend` audits required-field completeness only on pages that already have frontmatter — it never flags a page as "missing frontmatter." Special files (`index.md`, `log.md`, `hot.md`, `.manifest.json`, `_meta/taxonomy.md`, `_template.md`) are exempt.
+
+**If absent (no page in the wiki has frontmatter):** `wiki-tend` skips frontmatter checks. `wiki-update` writes plain markdown pages.
+
+---
+
+## Page template
+
+**If used:** Body structure for content pages:
+
+```markdown
+# Page Title
+
+One-paragraph summary.
+
+## Key Ideas
+
+- A fact explicitly stated by the source or codebase.
+- A generalization drawn from the source. ^[inferred]
+- A claim where sources disagree. ^[ambiguous]
+
+## Open Questions
+
+Unresolved items.
+```
+
+**If absent:** Pages are free-form.
+
+---
+
+## Provenance markers
+
+**If used:** Inline markers attached to claims indicate epistemic status.
+
+| State | Marker | Meaning |
+|---|---|---|
+| Extracted | *(no marker)* | Stated directly by source, docs, or code |
+| Inferred | `^[inferred]` | Synthesized or implied — not stated directly |
+| Ambiguous | `^[ambiguous]` | Sources disagree or evidence is unclear |
+
+Unmarked claims carry no enforced provenance — the convention treats them as extracted by default, but nothing in the tooling verifies the distinction. `wiki-update` applies markers when capturing; `wiki-tend` does not enforce them.
+
+**If absent:** No provenance is tracked; all claims are unmarked.
+
+---
+
+## Categorical layout
+
+**If used:** A folder convention for placing pages by kind. There's no canonical shape — your wiki's layout comes from what it's for. Pick what fits, mix shapes, or invent your own.
+
+A few example shapes:
+
+| Use case | Common top-level folders |
+|---|---|
+| **Developer notebook** | `concepts/`, `entities/`, `skills/`, `projects/<name>/` |
+| **Research wiki** | `papers/`, `topics/`, `methods/`, `datasets/`, `projects/<name>/` |
+| **Writing project** | `drafts/`, `characters/`, `worldbuilding/`, `notes/`, `archive/` |
+| **Recipe collection** | `recipes/`, `ingredients/`, `techniques/`, `meal-plans/` |
+| **Personal knowledge** | `journal/`, `learning/`, `contacts/`, `places/`, `interests/` |
+| **Team reference** | `runbooks/`, `decisions/`, `services/`, `people/`, `clients/` |
+
+Project-scoped content nests inside the wiki's project-grouping folder (commonly `projects/<name>/<sub-folder>/`, but `clients/<name>/` or `work/<name>/` follow the same pattern). Shared / external content typically lives under `shared/<name>/` (per `## Sharing & permissions`). `_archives/` is a conventional name for retired content / snapshots.
+
+Slugs for new pages are lowercase, hyphen-separated, ≤50 chars, descriptive.
+
+**Self-documenting layouts.** Each top-level folder gets a one-line "what goes here" description in `index.md` — under `## Spaces` if the folder is itself a space (has its own `index.md`), or under `## Items` if it's a plain folder you want surfaced. `wiki-update` reads those descriptions when classifying new content; without descriptions, the bare folder name is the only signal — name folders concretely (`recipes/` not `stuff/`) and routing still works, descriptions just make it more precise.
+
+`wiki-update`'s classification follows folder-name semantics first, then descriptions: a "sourdough recipe" matches `recipes/`, a "character bio" matches `characters/`, a "Python typing pattern" matches `concepts/` (or `notes/`, or whatever your wiki uses). When two folders are equally plausible the skill surfaces both options before writing; when none fit it asks, optionally creating a new folder for content that represents a recurring kind. Project-scoped content (identified by the user's intent — CWD is only a hint that disambiguates *which* project, never the trigger for project-vs-global) lands under whichever folder the wiki uses to group per-project content (`projects/`, `clients/`, `work/`, etc.).
+
+**If absent (no top-level folders at the wiki root other than `_meta/`, `_archives/`, `.git/`, or hidden directories):** `wiki-update` writes pages flat at the wiki root or asks the user where to place. `wiki-tend`'s cross-category scoring is skipped.
+
+---
+
+## Retrieval primitives
+
+Cost-tiered lookup table for `wiki-search`. Use the cheapest primitive that answers the question; escalate only when it cannot.
+
+| Need | Primitive | Cost |
+|---|---|---|
+| Page exists? Title/tags? | `index.md` scan or grep frontmatter | Cheapest |
+| 1–2 sentence preview | `summary:` frontmatter field | Cheap |
+| Specific claim or section | `grep -A 10 -B 2 "<term>" <file>` (or your harness's grep tool) | Medium |
+| Full page content | read the file | Expensive |
+
+Grep-style search is preferred over full reads. Full reads are capped at 3 candidates per query.
+
+---
+
+## Linking rules
+
+Wikilink and markdown-link syntax: see [obsidian-markdown](vendor/kepano/obsidian-markdown/SKILL.md). This section covers usage convention, not syntax.
+
+- Add up to 2 relevant wikilinks per page; never force irrelevant links.
+- Link the first natural mention only. Skip mentions inside code blocks or frontmatter.
+- Use the shortest link that resolves unambiguously.
+- `wiki-tend`'s cross-link pass scores candidates: exact name match (+4), shared tags ≥2 (+2), same project (+2), cross-category (+2), partial match (+1). Apply links only with score ≥3.
+
+---
+
+## Noise filter
+
+A heuristic for **knowledge-capture use cases** (research notes, technical wikis, developer notebooks) where the goal is "store what was hard to derive." Before writing a page, apply:
+
+- **Code answers it?** Skip — wiki the reasoning, not what code says.
+- **10-second search answers it?** Skip — wiki what took 30 minutes.
+- **Needed in 3 months?** If you'd have to re-research, wiki it.
+- **Already there?** Check `index.md`. Merge, don't duplicate.
+
+**Skip this filter** for content-store use cases where every entry is intentional regardless of derivation cost — recipe collections, personal journals, contact lists, team runbooks, etc. The "would you re-derive this?" test doesn't apply when the wiki *is* the source of truth, not a memory aid.
+
+---
+
+## `.git`
+
+Detection: a `.git` entry at the wiki root, whether a directory (regular repo) or a file (git submodule, worktree). Tools that need an authoritative answer should run `git -C <wiki-root> rev-parse --is-inside-work-tree`.
+
+**If present:** The wiki is also a git repository. Tools may surface git context (current branch, uncommitted changes, ahead/behind upstream) in their reports when relevant. Tools NEVER auto-commit or auto-push; all git operations are user-driven. See [`Sharing & permissions`](#sharing--permissions) for the recommended sharing pattern.
+
+**If absent:** No git context surfaced. Tools operate on the filesystem directly.
+
+---
+
+## `.obsidian/` integration
+
+**If present:** The wiki is intended to be opened in Obsidian. `wiki-tend`'s colorize step writes graph color groups into `.obsidian/graph.json` (only the `colorGroups` key; everything else preserved; backup written).
+
+Default colorize mode is `by-tag` (top 10 tags by usage, default palette below). `by-category` colors the categorical layout folders. `custom` honors user-provided mappings.
+
+Default palette (RGB ints) — tools may override:
+```
+[5142951, 15896107, 14767961, 7780786, 5873999,
+ 15583048, 11565217, 16751527, 10253663, 12234924]
+```
+
+**If absent:** Colorize step is skipped. The wiki is treated as a plain markdown directory.

wiki_spaces-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anfreire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wiki_spaces-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: wiki-spaces
+Version: 0.1.0
+Summary: Minimal nestable wiki — a folder + index.md, for any use case (notes, research, recipes, writing, team docs). Spec, conventions catalog, and reference skills.
+Project-URL: Homepage, https://github.com/anfreire/wiki-spaces
+Project-URL: Repository, https://github.com/anfreire/wiki-spaces
+Project-URL: Issues, https://github.com/anfreire/wiki-spaces/issues
+Author-email: André Ferreira <anfreire.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,knowledge-base,markdown,notes,obsidian,personal-wiki,wiki
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# wiki-spaces
+
+A wiki is a folder with `index.md`. That's the spec. Inside, anything goes: files, plain folders, or other spaces (folders that themselves carry `index.md`) — recursively. Zero contained spaces is a fine wiki. Deep nesting is too. Your shape is your call.
+
+Use it for whatever you want — research notes, writing drafts, recipes, project knowledge, a personal life wiki, a team reference. The spec is shape-agnostic; conventions are opt-in. `wiki-update` places new content by reading `index.md`'s `## Spaces` / `## Items` entries; `wiki-search` and `wiki-tend` operate against whatever shape the wiki has, with filesystem-glob fallbacks when the curated map is absent — see [`CONVENTIONS.md / Categorical layout`](CONVENTIONS.md#categorical-layout).
+
+Three tiers of opt-in: stop at the floor (`index.md` only), grow into navigable (`## Items` + `## Spaces` so the wiki maps itself), or fully managed (the `CONVENTIONS.md` catalog — taxonomy, logging, frontmatter, etc.). Each tier adds capability and a small contract; tools degrade gracefully where you haven't opted in.
+
+wiki-spaces ships:
+
+- The **spec** ([`AGENTS.md`](AGENTS.md)) — what counts as a wiki.
+- The **conventions catalog** ([`CONVENTIONS.md`](CONVENTIONS.md)) — opt-in markers tools detect.
+- Three **reference skills** AI agents use to work with your wiki:
+  - `wiki-search` — find content
+  - `wiki-update` — capture / save / sync new content
+  - `wiki-tend` — audit, normalize tags, cross-link, colorize
+
+One canonical wiki per user, located via `~/.config/wiki-spaces/config`. Plain markdown, Obsidian-flavored, version-controllable.
+
+## Just start (no install)
+
+The spec is a folder + `index.md`. If you don't need the reference skills yet, that's the whole setup:
+
+```sh
+mkdir -p ~/Wiki
+echo "# My Wiki" > ~/Wiki/index.md
+mkdir -p ~/.config/wiki-spaces
+printf 'wiki = %s/Wiki\n' "$HOME" > ~/.config/wiki-spaces/config
+```
+
+Start adding files. You now have a Tier 1 wiki. Install the skills later (steps below); they'll discover the wiki via the config you just wrote.
+
+## Setup (with the reference skills)
+
+### Paste this to your AI agent (recommended)
+
+```
+Install and set up wiki-spaces for me by following the instructions here:
+https://raw.githubusercontent.com/anfreire/wiki-spaces/main/references/SETUP.md
+```
+
+The agent fetches the briefing, asks what your wiki is for, picks tailored defaults, runs the install / scaffold / config writes, and confirms when done.
+
+### For LLM agents (non-interactive)
+
+```bash
+curl -s https://raw.githubusercontent.com/anfreire/wiki-spaces/main/references/SETUP.md
+```
+
+### For humans (manual)
+
+[`uv`](https://docs.astral.sh/uv/) is strongly recommended (handles Python provisioning + on-demand runs). Run on demand with no install:
+
+```bash
+uvx wiki-spaces install                                  # detected harnesses; add --all to cover every supported one
+uvx wiki-spaces init ~/Wiki --git                        # bare wiki at ~/Wiki; --with adds files, --folders adds dirs (see below)
+uvx wiki-spaces doctor --no-net
+```
+
+Or install permanently and drop the `uvx` prefix:
+
+```bash
+uv tool install wiki-spaces
+wiki-spaces install
+wiki-spaces init ~/Wiki --git                            # bare wiki; --with / --folders see below
+wiki-spaces doctor --no-net
+```
+
+No `uv`? Plain `pip` works too:
+
+```bash
+pip install --user wiki-spaces                           # or pipx install wiki-spaces
+wiki-spaces install
+wiki-spaces init ~/Wiki --git                            # bare wiki; --with / --folders see below
+wiki-spaces doctor --no-net
+```
+
+`init --with` accepts `log.md`, `_meta/taxonomy.md`, `.manifest.json`, `_template.md`, `hot.md` — opt-in conventions from `CONVENTIONS.md`. `--folders <names...>` creates top-level categorical directories — `--folders concepts entities projects` for a developer notebook, `--folders recipes ingredients techniques` for a recipe collection, `--folders drafts characters worldbuilding` for a writing project, and so on (see [`references/EXAMPLES.md`](references/EXAMPLES.md) for full shape examples). For nothing extra, leave both flags off; `index.md` is the only required file.
+
+After setup, your skills know everything via `${XDG_CONFIG_HOME:-~/.config}/wiki-spaces/config` (two keys: `wiki` and `repo`). Invoke `wiki-search`, `wiki-update`, `wiki-tend` from anywhere.
+
+For Cursor / Windsurf / GitHub Copilot / Aider (no skills concept), see [`references/HARNESS_INTEGRATION.md`](references/HARNESS_INTEGRATION.md).
+
+### Working from a source checkout (dev)
+
+```bash
+git clone https://github.com/anfreire/wiki-spaces.git ~/src/wiki-spaces
+~/src/wiki-spaces/scripts/install.py                     # same as `wiki-spaces install` but reads from the checkout
+~/src/wiki-spaces/scripts/init_wiki.py ~/Wiki --git
+~/src/wiki-spaces/scripts/doctor.py --no-net
+```
+
+The `scripts/*.py` shims are PEP 723 entries that forward to the `wiki_spaces` package — same code path as `uvx wiki-spaces`, just sourced from the local clone instead of PyPI.
+
+## How it works
+
+| | |
+|---|---|
+| **Discovery** | Skills read `~/.config/wiki-spaces/config` for the `wiki` path. CWD is a placement hint, never the discovery mechanism. |
+| **Conventions** | Obsidian-flavored: wikilinks, frontmatter, tags, Bases, `.obsidian/` graph integration. All optional per space; presence-detected. |
+| **Spaces** | Recursive (folders with their own `index.md`). Each is autonomous: own log, own taxonomy, own conventions. Shared/team spaces typically mount as git submodules under `shared/`. |
+| **Trust scope** | Tools distinguish *owned* spaces (yours) from *external* mounts (under `shared/`, foreign submodules, out-of-tree symlinks). Reads cross owned spaces by default; writes stay in the targeted space; external mounts require explicit opt-in. |
+
+## Read more
+
+- [`AGENTS.md`](AGENTS.md) — the spec. One page.
+- [`CONVENTIONS.md`](CONVENTIONS.md) — opt-in conventions catalog.
+- [`references/`](references/) — agent-facing setup, examples, and mounting playbooks.
+- [`skills/`](skills/) — the three reference skills.
+
+## Dependencies
+
+- **Python `>=3.11`** — the package's only hard runtime dep.
+- [`uv`](https://docs.astral.sh/uv/) — strongly recommended. Runs `uvx wiki-spaces` ephemerally, `uv tool install wiki-spaces` permanently, and provisions Python automatically. Plain `pip install wiki-spaces` (or `pipx`) works as a fallback if you can't / won't use uv.
+- `git` — optional. Recommended for backing up / sharing your wiki and for the dev-from-source flow.
+- [`kepano/obsidian-skills`](https://github.com/kepano/obsidian-skills) — `obsidian-markdown` and `obsidian-bases` are vendored under [`vendor/kepano/`](vendor/kepano/) (shallow clone + sparse copy, pinned by SHA) and ship inside the wheel. The reference skills defer to `obsidian-markdown` for wikilink / frontmatter / callout / embed syntax. `obsidian-bases` is vendored for future `.base` view tooling; no current procedure uses it.
+
+## Sharing wikis
+
+Shared / collaborative spaces are best handled as git repositories embedded in your canonical wiki via submodules. Push access on the remote is the de facto write-permission layer. See [`CONVENTIONS.md` / Sharing & permissions](CONVENTIONS.md#sharing--permissions) and [`references/MOUNT.md`](references/MOUNT.md).
+
+For local-only or private use, no git needed.
+
+## Prior art
+
+This project stands on three pieces of earlier work:
+
+- **Andrej Karpathy's "LLM Wiki" gist** ([gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) — the original idea: compile knowledge once into interconnected markdown files maintained by an LLM, instead of re-asking or re-RAG-ing.
+- **[Ar9av/obsidian-wiki](https://github.com/Ar9av/obsidian-wiki)** — a broader framework implementing the LLM Wiki pattern with ~30 skills across many AI coding harnesses. wiki-spaces extracts a smaller spec, commits to a single canonical wiki, and adds nestability for shared content.
+- **[kepano](https://github.com/kepano)** — Obsidian's lead designer, whose [`obsidian-skills`](https://github.com/kepano/obsidian-skills) are vendored as the syntax base.
+
+The [AGENTS.md](https://agents.md/) standard is used for the root agent-instruction file, with symlinks for harnesses that prefer their own filename.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).