repowiki-cli 0.5.0__py3-none-any.whl

repowiki/knowledge.py

@@ -0,0 +1,226 @@
+"""``repowiki knowledge``: append the knowledge-card task set, and aggregate
+knowledge outputs (_index.yaml / _module.yaml) at finalize time.
+
+Card categories default to the built-in six; ``--categories <file>`` replaces
+them wholesale with a repo-specific list (YAML/JSON), persisted in
+``state/knowledge_categories.json`` so later ``check``/``update`` rounds
+validate against the same set.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+import yaml
+
+from .errors import UsageError
+from .gitutil import run_git
+from .output import emit
+from .paths import WikiPaths, sanitize_component
+from . import tasks as task_builders
+from .scanner import scan
+from .state import TaskStore, now_iso
+
+_CATEGORY_ID_RE = re.compile(r"^[a-z][a-z0-9_]{1,39}$")
+MAX_CATEGORIES = 12
+
+
+def run_knowledge(paths: WikiPaths, as_json: bool, categories: str | None = None) -> int:
+    if categories:
+        custom = _load_category_file(paths.repo_root / categories)
+        paths.knowledge_categories_file.write_text(
+            json.dumps({"categories": custom}, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+    store = TaskStore(paths)
+    data = store.load()
+    if not data["tasks"]:
+        raise UsageError("请先运行 `repowiki plan <repo>`")
+    effective = effective_categories(paths)
+    added = store.add_tasks([
+        task_builders.build_knowledge_plan_task(paths, scan(paths.repo_root), effective)
+    ])
+    result = {
+        "ok": True,
+        "added": added,
+        "categories": [c["id"] for c in effective],
+        "note": "knowledge-plan 任务已就绪，领取执行后 check 会自动展开模块/卡片任务",
+    }
+    emit(result, _knowledge_human, as_json)
+    return 0
+
+
+def _knowledge_human(r: dict) -> str:
+    head = "已添加 knowledge-plan 任务" if r["added"] else "knowledge 任务集已存在"
+    cats = "、".join(r["categories"])
+    return f"{head}（类别清单：{cats}）\n{r['note']}"
+
+
+def _load_category_file(path) -> list[dict]:
+    """Parse + validate a user-supplied category list (YAML or JSON).
+
+    Entries are ``id`` strings or objects with ``id`` and optional
+    ``name``/``guidance``. The list replaces the built-in categories.
+    """
+    if not path.is_file():
+        raise UsageError(f"类别文件不存在: {path}")
+    raw = path.read_text(encoding="utf-8")
+    try:
+        data = (yaml.safe_load(raw) if path.suffix in (".yaml", ".yml")
+                else json.loads(raw))
+    except (yaml.YAMLError, json.JSONDecodeError) as e:
+        raise UsageError(f"类别文件解析失败（{path.name}）: {e}") from e
+    if not isinstance(data, list) or not data:
+        raise UsageError("类别文件必须是非空数组（字符串 id，或含 id/name/guidance 的对象）")
+    seen: set[str] = set()
+    cats: list[dict] = []
+    for i, item in enumerate(data):
+        where = f"categories[{i}]"
+        if isinstance(item, str):
+            item = {"id": item}
+        if not isinstance(item, dict):
+            raise UsageError(f"{where}: 必须是字符串或对象")
+        cid = str(item.get("id", "")).strip()
+        if not _CATEGORY_ID_RE.match(cid):
+            raise UsageError(
+                f"{where}: id 非法 `{cid}`（小写字母开头，仅小写字母/数字/下划线）"
+            )
+        if cid in seen:
+            raise UsageError(f"{where}: id 重复 `{cid}`")
+        seen.add(cid)
+        cats.append({
+            "id": cid,
+            "name": str(item.get("name", "")).strip() or cid,
+            "guidance": str(item.get("guidance", "")).strip(),
+        })
+    if len(cats) > MAX_CATEGORIES:
+        raise UsageError(f"类别过多（{len(cats)} > {MAX_CATEGORIES}）：机制卡片贵精不贵多")
+    return cats
+
+
+def effective_categories(paths: WikiPaths) -> list[dict]:
+    """The category list in force: user-supplied (persisted) or built-in."""
+    f = paths.knowledge_categories_file
+    if f.exists():
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            data = None
+        if isinstance(data, dict) and isinstance(data.get("categories"), list) and data["categories"]:
+            return data["categories"]
+    return [
+        {"id": cid, "name": guide}
+        for cid, guide in task_builders.DEFAULT_KNOWLEDGE_CATEGORIES
+    ]
+
+
+def scope_covers(scope_entry: str, path: str) -> bool:
+    """True when ``path`` falls under a plan scope entry like ``src/core/``,
+    ``src/core/**`` or ``**``."""
+    if scope_entry in ("**", "", "*"):
+        return True
+    prefix = scope_entry
+    for suffix in ("/**", "/*", "/"):
+        if prefix.endswith(suffix):
+            prefix = prefix[: -len(suffix)]
+            break
+    if not prefix:
+        return True
+    return path == prefix or path.startswith(prefix + "/")
+
+
+def _module_source_files(plan: dict, mod: dict) -> list[str]:
+    """Card-declared source files that fall under this module's scope — the
+    module docs describe structure, so their key files come from the cards."""
+    scopes = [s for s in (mod.get("scope") or []) if isinstance(s, str)]
+    files: set[str] = set()
+    for c in plan.get("cards", []):
+        if not isinstance(c, dict):
+            continue
+        for p in c.get("source_files") or []:
+            if any(scope_covers(s, p) for s in scopes):
+                files.add(p)
+    return sorted(files)
+
+
+def aggregate_knowledge(paths: WikiPaths, plan: dict, task_records: dict) -> str:
+    """Write knowledge/<locale>/_index.yaml and per-module _module.yaml.
+
+    Returns a human summary. Module -> directory mapping comes from the
+    knowledge_module task outputs (recorded when the task set was expanded).
+    """
+    mod_dirs: dict[str, str] = {}
+    used: set[str] = set()
+    for tid, t in task_records.items():
+        if t["kind"] == "knowledge_module":
+            dir_name = t["output"].rstrip("/").split("/")[-1]
+            mod_dirs[tid] = dir_name
+            used.add(dir_name)
+
+    if not mod_dirs:
+        return ""
+
+    def dir_of(mid: str) -> str | None:
+        return mod_dirs.get(mid)
+
+    modules_by_id = {m["id"]: m for m in plan.get("modules", []) if isinstance(m, dict)}
+    branch = ((run_git(paths.repo_root, "rev-parse", "--abbrev-ref", "HEAD") or "").strip()) or "main"
+
+    # per-module _module.yaml
+    for mid, mod in modules_by_id.items():
+        d = dir_of(mid)
+        if not d:
+            continue
+        mod_path = (mod.get("scope") or [""])[0]
+        content = {
+            "schema_version": 1,
+            "module_path": mod_path if mod_path != "**" else "",
+            "title": mod.get("title", ""),
+            "scope": mod.get("scope") or [],
+            "source_files": _module_source_files(plan, mod),
+            "depends_on": [dir_of(x) for x in (mod.get("depends_on") or []) if dir_of(x)],
+            "related_to": [dir_of(x) for x in (mod.get("related_to") or []) if dir_of(x)],
+        }
+        f = paths.knowledge_dir / d / "_module.yaml"
+        f.parent.mkdir(parents=True, exist_ok=True)
+        f.write_text(
+            "# 知识卡导出模块文件\n" + yaml.safe_dump(content, allow_unicode=True, sort_keys=False),
+            encoding="utf-8",
+        )
+
+    # _index.yaml with a module tree keyed by module_path
+    index_modules: dict[str, dict] = {}
+    for mid, mod in modules_by_id.items():
+        d = dir_of(mid)
+        if not d:
+            continue
+        key = (mod.get("scope") or [""])[0]
+        key = "" if key in ("**", "") else key
+        index_modules[key] = {
+            "dir_name": d,
+            "title": mod.get("title", ""),
+            "scope": mod.get("scope") or [],
+            "source_files": _module_source_files(plan, mod),
+            "children": [
+                (modules_by_id[c].get("scope") or [""])[0] or ""
+                for c in (mod.get("children") or []) if c in modules_by_id
+            ],
+            "depends_on": [dir_of(x) for x in (mod.get("depends_on") or []) if dir_of(x)],
+            "related_to": [dir_of(x) for x in (mod.get("related_to") or []) if dir_of(x)],
+        }
+    index = {
+        "schema_version": 1,
+        "locale": "zh-CN" if paths.locale == "zh" else "en",
+        "branch": branch,
+        "nodes_managed": True,
+        "exported_at": now_iso(),
+        "modules": index_modules,
+    }
+    paths.knowledge_dir.mkdir(parents=True, exist_ok=True)
+    (paths.knowledge_dir / "_index.yaml").write_text(
+        "# 知识卡导出索引文件\n" + yaml.safe_dump(index, allow_unicode=True, sort_keys=False),
+        encoding="utf-8",
+    )
+    cards = len(plan.get("cards", []))
+    return f"_index.yaml + {len(index_modules)} 个 _module.yaml（卡片 {cards} 张）"

repowiki/llms.py

@@ -0,0 +1,52 @@
+"""llms.txt / llms-full.txt export: the agent-consumption face of the wiki.
+
+The llms.txt convention (llmstxt.org) gives coding agents a linked index of a
+documentation set plus an optional full-text companion. repowiki's pages are
+plain markdown already, so both files are a deterministic byproduct of the same
+page collection the HTML site builds: links are relative paths into
+``.repowiki/`` — no agent, network or MCP server involved.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .i18n import strings
+from .paths import WikiPaths
+
+
+def write_llms(paths: WikiPaths, repo_name: str, pages: list[dict], nav: list[dict]) -> None:
+    """Write ``<locale>/llms.txt`` and ``<locale>/llms-full.txt``.
+
+    ``pages``/``nav`` are the collections assembled for the HTML site: page
+    dicts carry ``title``/``path`` (posix, relative to ``.repowiki/``)/``md``,
+    nav entries are ``{"title", "page"}`` singles or ``{"title", "children"}``
+    chapters whose leaves reference page indexes.
+    """
+    desc = strings(paths.locale)["site"]["llms_desc"].format(repo=repo_name)
+
+    lines = [f"# {repo_name} Wiki", "", f"> {desc}"]
+    for entry in nav:
+        lines += ["", f"## {entry['title']}", ""]
+        for leaf in entry.get("children", [entry]):
+            p = pages[leaf["page"]]
+            lines.append(f"- [{leaf['title']}]({_rel(paths, p['path'])})")
+
+    full = [f"# {repo_name} Wiki", "", f"> {desc}"]
+    for p in pages:
+        full += ["", "---", "", p["md"].rstrip()]
+
+    for name, text in (("llms.txt", "\n".join(lines) + "\n"),
+                       ("llms-full.txt", "\n".join(full) + "\n")):
+        out = paths.root / paths.locale / name
+        out.parent.mkdir(parents=True, exist_ok=True)
+        tmp = out.with_name(f".{out.name}.{os.getpid()}.tmp")
+        tmp.write_text(text, encoding="utf-8")
+        os.replace(tmp, out)
+
+
+def _rel(paths: WikiPaths, page_path: str) -> str:
+    """Link target for a page, relative to the directory holding llms.txt."""
+    rel = os.path.relpath(paths.root / page_path, paths.root / paths.locale)
+    return Path(rel).as_posix()

repowiki/metadata.py

@@ -0,0 +1,176 @@
+"""``repowiki finalize``: assemble <locale>/meta/repowiki-metadata.json.
+
+Parses every finished page for file:// references and builds the metadata
+document (source_files / code_snippets / knowledge_relations); runtime state
+stays in ``state/``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+
+from .catalog import flatten
+from .errors import UsageError
+from .gitutil import run_git
+from .output import emit
+from .paths import WikiPaths
+from .state import TaskStore, now_iso
+from .tasks import build_overview_task
+from .validate import extract_refs
+
+
+def _md5(s: str) -> str:
+    return hashlib.md5(s.encode("utf-8")).hexdigest()
+
+
+def run_finalize(paths: WikiPaths, as_json: bool) -> int:
+    store = TaskStore(paths)
+    data = store.load()
+    if not data["tasks"]:
+        raise UsageError("没有任务，请先运行 `repowiki plan <repo>`")
+
+    if "overview" not in data["tasks"]:
+        catalog = _require_catalog(paths)
+        nodes = flatten(catalog, paths.locale)
+        store.add_tasks([build_overview_task(paths, catalog.get("repo_name", ""), nodes)])
+        msg = "已创建阶段3 overview 任务，请领取执行后再次运行 finalize"
+        _emit_progress(as_json, msg)
+        return 3  # progress, not error: waiting for the overview task
+
+    catalog = _require_catalog(paths)
+    nodes = flatten(catalog, paths.locale)
+    missing_pages = [f"{n.id}({n.title})" for n in nodes if not (paths.root / n.output).is_file()]
+    if missing_pages:
+        raise UsageError(
+            f"catalog 中有 {len(missing_pages)} 个页面尚未生成: "
+            + ", ".join(missing_pages[:8])
+            + ("…" if len(missing_pages) > 8 else "")
+            + "（--max-pages 试跑后请补齐页面再 finalize，或 plan --replan 重来）"
+        )
+
+    unfinished = {tid: t["status"] for tid, t in data["tasks"].items() if t["status"] != "done"}
+    if unfinished:
+        raise UsageError(
+            f"仍有 {len(unfinished)} 个任务未完成: "
+            + ", ".join(f"{k}({v})" for k, v in list(unfinished.items())[:8])
+        )
+
+    by_id = {n.id: n for n in nodes}
+
+    source_files: dict[str, dict] = {}
+    snippets: dict[str, dict] = {}
+    relations: list[dict] = []
+    for n in nodes:
+        page_file = paths.root / n.output
+        refs = extract_refs(page_file.read_text(encoding="utf-8")) if page_file.is_file() else []
+        for path, start, end in refs:
+            sf_id = _md5(path)
+            if sf_id not in source_files:
+                source_files[sf_id] = {"id": sf_id, "path": path, "filename": path.rsplit("/", 1)[-1]}
+            relations.append({"type": "CONTAINS", "from": n.id, "to": sf_id})
+            if start is not None:
+                rng = f"{start}-{end}" if end and end != start else f"{start}-{start}"
+                sn_id = _md5(f"{path}:{rng}")
+                if sn_id not in snippets:
+                    snippets[sn_id] = {"id": sn_id, "path": path, "line_range": rng}
+                relations.append({"type": "REFERENCED_BY", "from": sn_id, "to": n.id})
+
+    repo_name = catalog.get("repo_name") or paths.repo_root.name
+    metadata = {
+        "wiki_repo": {
+            "id": _md5(str(paths.repo_root)),
+            "name": repo_name,
+            "progress_status": "completed",
+            "wiki_present_status": "COMPLETED",
+            "locale": paths.locale,
+            "last_commit_id": (run_git(paths.repo_root, "rev-parse", "HEAD") or "").strip() or None,
+            "generated_at": now_iso(),
+        },
+        "wiki_catalogs": [
+            {
+                "id": n.id,
+                "repo_id": _md5(str(paths.repo_root)),
+                "name": n.title,
+                "description": n.slug,
+                "prompt": n.page_brief,
+                "parent_id": n.parent_id,
+                "dependent_files": ", ".join(n.dependent_files),
+                "progress_status": "completed",
+            }
+            for n in nodes
+        ],
+        "wiki_items": [{"catalog_id": n.id, "title": n.title} for n in nodes],
+        "source_files": sorted(source_files.values(), key=lambda x: x["path"]),
+        "code_snippets": sorted(snippets.values(), key=lambda x: (x["path"], x["line_range"])),
+        "knowledge_relations": relations,
+    }
+
+    overview = paths.overview_file
+    if overview.is_file():
+        metadata["wiki_overview"] = overview.read_text(encoding="utf-8")
+    else:
+        metadata["wiki_overview"] = "No overview yet."
+
+    knowledge_summary = _aggregate_knowledge_if_present(paths, store)
+
+    paths.meta_dir.mkdir(parents=True, exist_ok=True)
+    tmp = paths.metadata_file.with_name(".metadata.tmp")
+    tmp.write_text(json.dumps(metadata, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, paths.metadata_file)
+
+    summary = {
+        "ok": True,
+        "metadata": str(paths.metadata_file),
+        "pages": len(nodes),
+        "source_files": len(source_files),
+        "code_snippets": len(snippets),
+        "knowledge_relations": len(relations),
+        "knowledge": knowledge_summary,
+    }
+    removed = store.cleanup_runtime()
+    summary["cleaned_runtime"] = removed
+    emit(summary, _fmt_summary, as_json)
+    return 0
+
+
+def _fmt_summary(s: dict) -> str:
+    lines = [
+        f"✓ metadata 已生成: {s['metadata']}",
+        f"  页面 {s['pages']} · 引用文件 {s['source_files']} · 代码片段 {s['code_snippets']} · 知识关系 {s['knowledge_relations']}",
+    ]
+    if s["knowledge"]:
+        lines.append(f"  知识库: {s['knowledge']}")
+    if s.get("cleaned_runtime"):
+        lines.append(f"  已清理运行时产物: state/{', state/'.join(s['cleaned_runtime'])}（保留 index/catalog/knowledge 供增量更新）")
+    return "\n".join(lines)
+
+
+def _emit_progress(as_json: bool, msg: str) -> None:
+    emit({"ok": True, "waiting": True, "detail": msg,
+          "next_action": "执行 overview 任务后再次运行 finalize"},
+         lambda r: r["detail"], as_json)
+
+
+def _require_catalog(paths: WikiPaths) -> dict:
+    if not paths.catalog_file.exists():
+        raise UsageError("state/catalog.json 不存在：请先完成 catalog 任务")
+    try:
+        return json.loads(paths.catalog_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise UsageError(
+            f"state/catalog.json 损坏（{e}）：可手工修复该文件，或 `repowiki plan --replan` 重新规划"
+        ) from e
+
+
+def _aggregate_knowledge_if_present(paths: WikiPaths, store: TaskStore) -> str:
+    if not paths.knowledge_plan_file.exists():
+        return ""
+    try:
+        plan = json.loads(paths.knowledge_plan_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return "knowledge.json 解析失败，已跳过聚合"
+    from .knowledge import aggregate_knowledge
+
+    return aggregate_knowledge(paths, plan, store.load()["tasks"])

repowiki/output.py

@@ -0,0 +1,34 @@
+"""Dual-format output: the one seam every command prints through.
+
+``--json`` mode dumps the result dict verbatim; human mode renders it with a
+per-command formatter. Routing both representations through one seam keeps
+them in lockstep (a new field lands in both or neither) and gives the human
+branch — historically untested copy — a callable test surface.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Callable
+
+Human = Callable[[dict], str]
+
+
+def emit(result: dict, human: Human, as_json: bool, file=None) -> None:
+    """Print ``result`` as JSON, or via ``human(result)`` (skipped when empty)."""
+    if as_json:
+        print(json.dumps(result, ensure_ascii=False, indent=2), file=file)
+    else:
+        text = human(result)
+        if text:
+            print(text, file=file)
+
+
+def emit_error(kind: str, detail: str, as_json: bool) -> None:
+    """Report a CLI error: JSON contract on stdout, human copy on stderr."""
+    prefix = {"conflict": "conflict: ", "state_corrupt": "state error: "}.get(kind, "error: ")
+    emit({"ok": False, "error": kind, "detail": detail},
+         lambda r: prefix + r["detail"],
+         as_json,
+         file=None if as_json else sys.stderr)

repowiki/paths.py

@@ -0,0 +1,176 @@
+"""Path derivation and normalization rules (all deterministic).
+
+- Chapter titles become directory/file names: NFC normalize, replace
+  filesystem-illegal characters with full-width counterparts, strip
+  control characters and leading/trailing dots or spaces.
+- Name collisions get a ``__2`` style suffix.
+- GitHub-style heading anchors keep CJK characters, drop punctuation
+  (including ``：`` and ``:``) and turn spaces into ``-``.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import Path
+
+from .i18n import DEFAULT_LOCALE, SUPPORTED
+
+_ILLEGAL_MAP = {
+    "/": "／",
+    "\\": "＼",
+    ":": "：",
+    "*": "＊",
+    "?": "？",
+    '"': "＂",
+    "<": "＜",
+    ">": "＞",
+    "|": "｜",
+}
+_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f]")
+
+_GITHUB_PUNCT_RE = re.compile(
+    r"[" + re.escape("`~!#$%^&*()+=[]{}\\|:;'\",.<>/?_-—─·•„“”«»…！￥（）【】《》「」：；‘’\"，。、？") + r"]"
+)
+_GITHUB_SPACE_RE = re.compile(r"\s+")
+
+
+def nfc(s: str) -> str:
+    return unicodedata.normalize("NFC", s)
+
+
+def sanitize_component(title: str) -> str:
+    """Title -> single path component (directory or file stem)."""
+    s = nfc(title).strip()
+    s = _CONTROL_RE.sub("", s)
+    for bad, full in _ILLEGAL_MAP.items():
+        s = s.replace(bad, full)
+    s = s.strip(" .")
+    return s or "untitled"
+
+
+def unique_name(name: str, used: set[str]) -> str:
+    """Return ``name`` or ``name__2``, ``name__3``... so it is unique in ``used``."""
+    if name not in used:
+        used.add(name)
+        return name
+    n = 2
+    while f"{name}__{n}" in used:
+        n += 1
+    candidate = f"{name}__{n}"
+    used.add(candidate)
+    return candidate
+
+
+def github_anchor(heading: str) -> str:
+    """GitHub-style anchor: lowercase, delete punctuation (CJK included),
+    whitespace -> '-'.  ``附录：一键运行清单`` -> ``附录一键运行清单``;
+    ``BM25 关键词`` -> ``bm25-关键词``.
+    """
+    s = nfc(heading).strip().lower()
+    s = _GITHUB_PUNCT_RE.sub("", s)
+    s = _GITHUB_SPACE_RE.sub("-", s)
+    s = re.sub(r"-{2,}", "-", s).strip("-")
+    return s
+
+
+class WikiPaths:
+    """Resolves every location the tool reads/writes under a repository.
+
+    The output locale follows the target repository: explicit argument wins,
+    else the persisted ``state/locale`` file, else the default (zh).
+    """
+
+    def __init__(self, repo_root: str | Path, locale: str | None = None):
+        self.repo_root = Path(repo_root).resolve()
+        self._locale = locale
+
+    @property
+    def locale(self) -> str:
+        if self._locale is None:
+            f = self.state_dir / "locale"
+            try:
+                value = f.read_text(encoding="utf-8").strip()
+            except OSError:
+                value = ""
+            self._locale = value if value in SUPPORTED else DEFAULT_LOCALE
+        return self._locale
+
+    def persist_locale(self, locale: str) -> None:
+        """Pin the output locale for this and all later commands."""
+        if locale not in SUPPORTED:
+            raise ValueError(f"unsupported locale: {locale}")
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        (self.state_dir / "locale").write_text(locale, encoding="utf-8")
+        self._locale = locale
+
+    @property
+    def root(self) -> Path:
+        return self.repo_root / ".repowiki"
+
+    @property
+    def state_dir(self) -> Path:
+        return self.root / "state"
+
+    @property
+    def tasks_dir(self) -> Path:
+        return self.state_dir / "tasks"
+
+    @property
+    def claims_dir(self) -> Path:
+        return self.state_dir / "claims"
+
+    @property
+    def catalog_file(self) -> Path:
+        return self.state_dir / "catalog.json"
+
+    @property
+    def knowledge_plan_file(self) -> Path:
+        return self.state_dir / "knowledge.json"
+
+    @property
+    def knowledge_categories_file(self) -> Path:
+        return self.state_dir / "knowledge_categories.json"
+
+    @property
+    def index_file(self) -> Path:
+        return self.state_dir / "index.json"
+
+    @property
+    def content_dir(self) -> Path:
+        return self.root / self.locale / "content"
+
+    @property
+    def meta_dir(self) -> Path:
+        return self.root / self.locale / "meta"
+
+    @property
+    def knowledge_dir(self) -> Path:
+        return self.root / "knowledge" / self.locale
+
+    @property
+    def metadata_file(self) -> Path:
+        return self.meta_dir / "repowiki-metadata.json"
+
+    @property
+    def site_file(self) -> Path:
+        return self.root / self.locale / "wiki.html"
+
+    @property
+    def llms_file(self) -> Path:
+        return self.root / self.locale / "llms.txt"
+
+    @property
+    def llms_full_file(self) -> Path:
+        return self.root / self.locale / "llms-full.txt"
+
+    @property
+    def overview_file(self) -> Path:
+        return self.meta_dir / "wiki-overview.md"
+
+    def ensure(self) -> None:
+        for d in (self.state_dir, self.tasks_dir, self.claims_dir, self.content_dir, self.meta_dir):
+            d.mkdir(parents=True, exist_ok=True)
+
+    def task_spec(self, task_id: str) -> Path:
+        return self.tasks_dir / f"{task_id}.md"