mirror of
https://github.com/Ar9av/obsidian-wiki.git
synced 2026-09-14 20:36:34 +08:00
ar9av
4bf87a8d19
Two strands of work. Session brain — a topic graph over raw agent session history, so you can find the session where something happened instead of remembering its UUID. Reads every Claude transcript plus the pruned sessions that survive only as prompts in history.jsonl, clusters them with local TF-IDF and community detection (no embeddings, no API calls, no new dependencies), and writes a sidecar at ~/.claude/session-brain/ — the vault is never touched. Ships five modules, the sessions-* CLI commands, an interactive graph.html, and the /session-brain and /wiki-sessions skills. This is retrieval, deliberately distinct from wiki-history-ingest, which distils sessions into permanent vault pages. Docs — README.md was 598 lines and put trust-check flags and a 17-row agent matrix in front of anyone evaluating the project. Cut it to a 129- line landing page (problem statement, 60-second install, four blocks of runnable commands, graph screenshot, why-not-a-notes-folder) and move the reference material into docs/: installation, agents, skills, cli, configuration, architecture, session-brain, contributing. README_TW.md mirrors the new structure; docs/ stays English-only for now. The restructure also closed real drift: - Ten skills existed but appeared in no reference — session-brain, session-search, wiki-dedup, wiki-digest, wiki-import, wiki-context-pack, wiki-stage-commit, wiki-switch, vault-skill-factory, and obsidian-layout-adjustment. - SETUP.md listed 12 of 39 skills and still claimed "no scripts, no dependencies" despite the pip package. It is now a signpost into docs/. - Eight config variables were undocumented anywhere, including WIKI_STAGED_WRITES, which wiki-setup prompts for and three skills read. Added to .env.example and docs/configuration.md. - sessions-name and a number of CLI flags were missing from the docs. Two details worth noting. README links are absolute GitHub URLs because pyproject sets readme = "README.md" as the PyPI long_description, and PyPI resolves relative hrefs against pypi.org rather than the repo — docs/ links would have 404'd on the package page. And three doc-drift guards asserted their facts against README.md; since those facts moved rather than disappeared, the assertions were repointed at the page that now owns each one instead of padding content back into the README. Also gitignore /vault/ (a local knowledge vault, not a fixture) and the packed browser extension. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
# Contributing
|
|
|
|
This is early. The skills work, but there's room to make the brain smarter: better cross-referencing, sharper deduplication, bigger vaults, new ingest sources. If you've been chewing on this problem or have a workflow that could be a skill, PRs are welcome.
|
|
|
|
## Adding a new skill
|
|
|
|
1. Create a folder in `.skills/your-skill-name/`
|
|
2. Add a `SKILL.md` with YAML frontmatter (`name`, `description`) and markdown instructions
|
|
3. Run `bash setup.sh` to symlink it into every agent directory
|
|
4. Test by saying something to your agent that matches the description
|
|
|
|
The `description` is load-bearing — it's the only thing an agent sees when deciding whether your skill is relevant. Write it as a list of the phrases a user would actually say, and state what the skill is *not* for when it's easily confused with a neighbour.
|
|
|
|
See [`.skills/skill-creator/SKILL.md`](../.skills/skill-creator/SKILL.md) for the full guide, or just ask your agent to run `/skill-creator`.
|
|
|
|
When you add a skill, also add it to the [skills reference](skills.md) and the routing table in `AGENTS.md`.
|
|
|
|
## Keeping both READMEs in sync
|
|
|
|
`README.md` (English) and `README_TW.md` (Traditional Chinese) are **one documentation surface**. Keep headings, examples, links, and user-facing behavior structurally and semantically aligned.
|
|
|
|
Syncing is advisory, not a merge gate — the `readme-translation-drift` CI job only reports when the translation falls behind. To catch up:
|
|
|
|
```bash
|
|
python tools/check_readme_sync.py
|
|
```
|
|
|
|
It lists the commits that changed `README.md` without a later `README_TW.md` update, plus the pending English diff. Translate and backfill those into `README_TW.md`. Reviewers assess translation quality.
|
|
|
|
The `docs/` pages are English-only for now.
|
|
|
|
## Repo conventions
|
|
|
|
- `.skills/` is the source of truth. Everything else — `.claude/skills/`, `~/.codex/skills/`, and so on — is symlinks created by setup. Never edit a symlinked copy.
|
|
- `CLAUDE.md`, `GEMINI.md`, and `.hermes.md` are symlinks to `AGENTS.md`. Edit `AGENTS.md`.
|
|
- New config variables belong in three places: `.env.example`, [`docs/configuration.md`](configuration.md), and the skill that reads them.
|
|
- New CLI subcommands belong in [`docs/cli.md`](cli.md).
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
Tests live in `tests/`. Skill behavior that can be asserted deterministically (config resolution, manifest handling, graph math, session indexing) has coverage there; the LLM-driven parts don't.
|