diff --git a/skills/mappa-knowledge/SKILL.md b/skills/mappa-knowledge/SKILL.md index 6bbf357..8cea1a1 100644 --- a/skills/mappa-knowledge/SKILL.md +++ b/skills/mappa-knowledge/SKILL.md @@ -1,7 +1,7 @@ --- name: mappa-knowledge author: ours -version: 1.3.0 +version: 1.4.0 description: > Цикл работы со знаниями проекта в Mappa (Karpathy LLM Wiki, канал = mappa-сущности): ingest → query → lint + граф-слой для @@ -42,7 +42,7 @@ README/ADR (не персистентная база знаний), проект ## Три слоя (не смешивать) -1. **Raw-источники** — `sources/` страницы. Иммутабельны: читай, не +1. **Raw-источники** — `summaries/` страницы. Иммутабельны: читай, не редактируй (единственное исключение — блок-цитата `> Status` по явной просьбе пользователя). 2. **Вики** — остальные страницы (entities/concepts/packages/contradictions/open-questions/overview). @@ -101,7 +101,7 @@ per-type рефы полными именами (`[[task:N]]`/`[[inbox:N]]`). 1. Прочитай источник полностью. 2. Извлеки: entities, concepts, packages, кросс-резы. -3. Создай `sources/` — одну страницу-резюме на источник (~50–150 строк; +3. Создай `summaries/` — одну страницу-резюме на источник (~50–150 строк; ссылку на raw клади в frontmatter `raw_path` + `ingested:`). 4. Для каждой затронутой страницы: - есть → обнови (`wiki_update(project, id, body, version)` — version свежая @@ -195,7 +195,7 @@ updated: 2026-08-24 --- ``` -Страницы `sources/` дополнительно несут `ingested: YYYY-MM-DD` и `raw_path: …`. +Страницы `summaries/` дополнительно несут `ingested: YYYY-MM-DD` и `raw_path: …`. `contradictions/` — `status: open | resolved | accepted-divergence` и `affects:`. `open-questions/` — `status: open | answered | obsolete` и `touches:`. @@ -203,7 +203,7 @@ updated: 2026-08-24 - `kebab-case`, **только латиница**. Кириллицу/др. скрипты транслитерируй (`план переписывания` → `ozon-client-rewrite`). Оригинальный title — в H1 и frontmatter. -- `entities/`, `concepts/`, `packages/`, `sources/`, +- `entities/`, `concepts/`, `packages/`, `summaries/`, `contradictions/`, `open-questions/`. ### Оп-лог — таблица `logs`, не страница @@ -224,7 +224,7 @@ level/since/component/entity, retention 14d). Ручную `log`-страниц | Ситуация | Что трогаем | |---|---| -| Ingest одного документа | `sources/` (новая) + 3–15 entities/concepts/packages (+ опционально `index`) | +| Ingest одного документа | `summaries/` (новая) + 3–15 entities/concepts/packages (+ опционально `index`) | | Query | (чтение) + возможно новая страница | | Query реляционный | graph_* (BFS), не чтение | | Lint | (чтение) + graph_backlinks/stats для сирот | @@ -232,8 +232,8 @@ level/since/component/entity, retention 14d). Ручную `log`-страниц ## Частые ошибки -- **Правка `sources/`.** Нельзя. Только статус-блок по явной просьбе. -- **Дамп сырья в `sources/`.** Резюме — это резюме. Ссылайся на raw, не копируй. +- **Правка `summaries/`.** Нельзя. Только статус-блок по явной просьбе. +- **Дамп сырья в `summaries/`.** Резюме — это резюме. Ссылайся на raw, не копируй. - **Молчаливые перезаписи.** Новый источник противоречит странице — пометь блоком `> **Противоречие:**`; не затирай. - **Нарративный оп-лог.** Не веди его руками: сервис пишет logs сам (admin.logs). @@ -253,7 +253,7 @@ level/since/component/entity, retention 14d). Ручную `log`-страниц ## Red flags - Реляционный вопрос → читаешь страницу вместо `graph_*`. -- Правка `sources/` или молчаливая перезапись противоречия. +- Правка `summaries/` или молчаливая перезапись противоречия. - Wiki-мутация update без version (last-write-wins) или create с выдуманным claim. - Нарративный оп-лог руками. diff --git a/skills/project-bootstrap/SKILL.md b/skills/project-bootstrap/SKILL.md index a7f9c75..4949aff 100644 --- a/skills/project-bootstrap/SKILL.md +++ b/skills/project-bootstrap/SKILL.md @@ -1,7 +1,7 @@ --- name: project-bootstrap author: ours -version: 2.1.0 +version: 2.2.0 description: > Initializes or upgrades a project in the current folder: git, .gitignore, README.md, .wiki/ using Karpathy's method, .tasks/ for task tracking, AGENTS.md (canon) with @@ -198,7 +198,7 @@ v2 (mappa wiki-тулы). Файловый `.wiki/` — только для пр entities/ ← entity pages (people, services, modules) — empty .gitkeep concepts/ ← concept / design decision pages — empty .gitkeep packages/ ← package pages — empty .gitkeep - sources/ ← one summary per ingested source — empty .gitkeep + summaries/ ← one summary per ingested source (LLM, raw_path) — empty .gitkeep ``` Page-level workflow (ingest, query, lint) and file formats are owned by the @@ -223,7 +223,7 @@ file overrides the skill where they conflict. - `entities/` — discrete things the project tracks (people, services, modules). - `concepts/` — recurring ideas, design decisions, gotchas. - `packages/` — code packages this project produces or consumes. -- `sources/` — one summary page per ingested external doc; frontmatter carries `ingested:` and `raw_path:`. +- `summaries/` — one summary page per ingested external doc; frontmatter carries `ingested:` and `raw_path:`. - `overview.md` — single project-wide overview. ## Naming @@ -298,7 +298,7 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`. **Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit. -Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files. +Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../summaries/`, and never modifies raw files. For large or path-sensitive sources that live outside the repo, register them here: @@ -307,7 +307,7 @@ For large or path-sensitive sources that live outside the repo, register them he \`\`\` ``` -The empty subdirectories (`entities/`, `concepts/`, `packages/`, `sources/`) +The empty subdirectories (`entities/`, `concepts/`, `packages/`, `summaries/`) each get a `.gitkeep` so git tracks them. --- diff --git a/skills/using-markitdown/SKILL.md b/skills/using-markitdown/SKILL.md index 73ea725..3d8f029 100644 --- a/skills/using-markitdown/SKILL.md +++ b/skills/using-markitdown/SKILL.md @@ -1,7 +1,7 @@ --- name: using-markitdown author: ours -version: 1.0.1 +version: 1.1.0 description: Use when capturing external content into a markdown-based knowledge base, wiki `raw/` directory, or any pipeline that must preserve the source's full text — for web pages, PDFs, DOCX/PPTX/XLSX, EPUB, CSV/JSON/XML, ZIP archives, images (with OCR/EXIF), audio (with transcription), or YouTube URLs. Also use when WebFetch returned an LLM-summarized version but the raw content is what's needed. --- @@ -52,7 +52,7 @@ No mount caveats: the CLI is a normal local process. The old Docker `-v` mount t 1. markitdown "https://example.com/foo.pdf" -o .wiki/raw/.md (kebab-case, Latin only) 2. Inspect the head of the result. If it looks like a sign-in/cookie/consent page, abort — ask the user for an alternative (manual save, paste, authenticated source). 3. Register the new file in .wiki/raw/README.md. -4. Hand off to the wiki ingest workflow (creates sources/.md summary + entity/concept updates). +4. Hand off to the wiki ingest workflow (creates summaries/.md summary + entity/concept updates). ``` For a huge (book-length) document, write straight to a file with `-o` and summarize *from the saved file* — do not pipe the whole markdown through working context. @@ -63,7 +63,7 @@ For a huge (book-length) document, write straight to a file with `-o` and summar |---|---|---| | Output is a Google/Microsoft sign-in page in some random language | URI behind auth wall | Ask user to export the content manually (Save as PDF, copy-paste) and put it in `raw/` | | Output is mostly nav/cookie banner text | Site is JS-rendered or anti-bot | Try the cached or print URL; or ask user for HTML export | -| Output lacks images / diagrams | Markdown is text-only by design | Save the original asset separately under `raw/assets/`; reference it from the `sources/` summary | +| Output lacks images / diagrams | Markdown is text-only by design | Save the original asset separately under `raw/assets/`; reference it from the `summaries/` summary | | `markitdown: command not found` | CLI not on `PATH` | Confirm with `markitdown --version` (expect `markitdown 0.1.6`); install with `pip install markitdown[all]` if missing | | Huge output (book-length) | Whole document converted in one call | Use `-o ` to save raw, then summarize *from the saved file* — do not hold the entire markdown in working context | diff --git a/skills/using-projects-meta/README.md b/skills/using-projects-meta/README.md index 1339284..947dce4 100644 --- a/skills/using-projects-meta/README.md +++ b/skills/using-projects-meta/README.md @@ -118,9 +118,9 @@ permission to plan, not to commit. | `mcp__projects-meta__tasks_update` | `target_project`, `slug` + ≥1 mutable field | Sha-based optimistic lock; 422 on conflict | | `mcp__projects-meta__tasks_close` | `target_project`, `slug` (+ opt `note`) | Marks task 🟢 done with identity-footer | | `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` | Three commits: `/.md` + `index.md` + `log.md` | -| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` | Move `raw/.md` → `sources/.md` | +| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` | Move `raw/.md` → `summaries/.md` | -`type` ∈ `entities` / `concepts` / `packages` / `sources` / `raw`. +`type` ∈ `entities` / `concepts` / `packages` / `summaries` / `raw`. `target_project` = Gitea repo name, or `_meta` (meta-tasks / meta-wiki repos from `auth.toml`). diff --git a/skills/using-projects-meta/SKILL.md b/skills/using-projects-meta/SKILL.md index 139ff1d..e6fa20d 100644 --- a/skills/using-projects-meta/SKILL.md +++ b/skills/using-projects-meta/SKILL.md @@ -1,7 +1,7 @@ --- name: using-projects-meta author: ours -version: 1.2.0 +version: 1.3.0 description: Use when working across multiple projects on one or many machines — cross-project task aggregation (`mcp__projects-meta__tasks_*`), shared Gitea-backed wiki query / ingest (`mcp__projects-meta__knowledge_*`), or sync diagnostics (`mcp__projects-meta__meta_status`). Triggers on phrases like "across all projects", "what's on the boards", "check shared wiki", "search projects-wiki", "ingest into shared wiki", "что у меня на досках", "по всем проектам", "общая вики", "cross-project status", or any time the user wants to see / mutate state in another repo than the current cwd. v1.1.0 mandates a Step 0 freshness gate (probe `meta_status`, sync if stale, pull `projects-wiki` before shared-wiki writes) — see SKILL body. Mutation tools require two-step preview → confirm. Skip for the **current** project's tasks/wiki — those live on disk in `.tasks/` / `.wiki/`. --- @@ -12,7 +12,7 @@ description: Use when working across multiple projects on one or many machines `projects-meta-mcp` is a local stdio MCP server. Two responsibilities: 1. **Cross-project task aggregation** — parses `.tasks/STATUS.md` from every repo on the user's Gitea, caches them in `~/.cache/projects-mcp/tasks.json`. Read tools (`tasks_aggregate`, `tasks_search`, `tasks_get`) hit the cache. Mutations (`tasks_create`, `tasks_update`, `tasks_close`) commit back to Gitea with sha-based optimistic lock. -2. **Shared knowledge wiki** — single Gitea repo (`projects-wiki`) cloned at `~/projects/projects-wiki/` with content at `~/projects/projects-wiki/.wiki/`, structured as packages / concepts / entities / sources / raw. `knowledge_search` + `knowledge_get` for queries, `knowledge_ingest` + `knowledge_promote` for writes. +2. **Shared knowledge wiki** — single Gitea repo (`projects-wiki`) cloned at `~/projects/projects-wiki/` with content at `~/projects/projects-wiki/.wiki/`, structured as packages / concepts / entities / summaries / raw. `knowledge_search` + `knowledge_get` for queries, `knowledge_ingest` + `knowledge_promote` for writes. Source of truth: Gitea (`https://git.kzntsv.site`, owner `OpeItcLoc03`). Cache and clone are local convenience. @@ -140,8 +140,8 @@ Use MCP only for **other** projects, **other** machines, or **shared** wiki cont | `mcp__projects-meta__tasks_create` | `target_project`, `slug`, `description`, `next_action` (+ opt `where_stopped`, `status`, `blocker`, `branch`, `source_project`) | Append block to `/.tasks/STATUS.md` via Gitea commit | | `mcp__projects-meta__tasks_update` | `target_project`, `slug` + ≥1 of `where_stopped` / `next_action` / `blocker` / `branch` / `description` / `status` | Sha-based optimistic lock; 422 on conflict | | `mcp__projects-meta__tasks_close` | `target_project`, `slug` (+ opt `note`) | Sets task to 🟢 done; appends identity-footer | -| `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Three commits: `/.md` + `index.md` + `log.md`. `type` ∈ entities / concepts / packages / sources / raw | -| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/.md` → `sources/.md` with auto `raw_path` link | +| `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Three commits: `/.md` + `index.md` + `log.md`. `type` ∈ entities / concepts / packages / summaries / raw | +| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/.md` → `summaries/.md` with auto `raw_path` link | `target_project` is **qualified** `/` (e.g. `victor/books`, `OpeItcLoc03/skills`), or the literal `agenda` for the cross-project meta-board (resolves via `agenda_tasks_repo` in `auth.toml`). Bare names (`books`) are rejected with a hint to use the qualified form. Cross-cutting design: shared wiki → `concepts/projects-meta-multi-owner`. @@ -225,7 +225,7 @@ User: "close `[projects-meta-skills]` in skills" | Acting on a stale `tasks_aggregate` without checking `meta_status` | Step 0 — Freshness gate is mandatory. If `cache_age_minutes` > 10 (or errors > 0), run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js` first. | | Skipping `git -C ~/projects/projects-wiki pull` before `knowledge_ingest` / `knowledge_promote` | sha-based optimistic lock will reject the commit (422) and the failure is opaque. Pull is unconditional for shared-wiki writes — fast-forward is a no-op when current. | | Treating sync 401/403 as "MCP is fine, the page just doesn't exist yet" | 401/403 means the Gitea token is dead. Stop, tell the user to rotate `gitea_token` in `~/.config/projects-mcp/auth.toml`. Never guess on stale data. | -| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `sources` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. | +| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `summaries` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. | | Vague `knowledge_search` queries ("auth", "config") | Specific multi-word queries return targeted snippets; vague ones return noise. | | Forgetting `domain="all"` when searching across families | Default `domain` is auto-detected from cwd; use `"all"` if the wiki page lives in a different family. | | Passing bare project name (`target_project: "books"`) to mutation tools | v2.x rejects bare names. Use qualified `/` (e.g. `victor/books`, `OpeItcLoc03/skills`). Literal `agenda` is the only exception (cross-project meta-board). |