open-wiki-spec 0.2.0 → 0.2.1

package/README.md

@@ -5,7 +5,7 @@
 <!-- Badges -->
 [![npm version](https://img.shields.io/npm/v/open-wiki-spec)](https://www.npmjs.com/package/open-wiki-spec)
 [![license](https://img.shields.io/npm/l/open-wiki-spec)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-674%20passed-brightgreen)](#)
+[![tests](https://img.shields.io/badge/tests-805%20passed-brightgreen)](#)
 
 ---
 
@@ -128,10 +128,12 @@ The retrieval pipeline uses **weighted scoring signals**, not free-form LLM judg
 |--------|--------|
 | Exact title match | +40 |
 | Alias match | +35 |
+| Semantic similarity | +30 |
 | Active change overlap | +25 |
 | Same system | +20 |
 | Same feature link | +20 |
-| Full-text match | +15 |
+| Partial title match | +20 |
+| Full-text match | +15 / +8 |
 | Shared source | +10 |
 | Shared decision | +10 |
 | Backlink proximity | +10 |
@@ -145,7 +147,9 @@ Classification is rule-based with thresholds:
 | `new_feature` | Nothing similar found. Create new Feature + Change. |
 | `needs_confirmation` | Ambiguous results. Ask the user to choose. |
 
-Results are deterministic, explainable, and debuggable. No embedding service required.
+Results are deterministic, explainable, and debuggable.
+
+**v0.2.0+** also includes **semantic search** via local embeddings (`multilingual-e5-small`). When available, a 10th scoring signal (`semantic_similarity: +30`) catches meaning-based matches that keyword search misses — e.g., "새 사용자를 받고 싶어" finds "회원가입" Feature even without keyword overlap. The embedding model downloads automatically on first use (~113MB, cached locally). Use `--keywords` to let the agent pass refined search terms directly.
 
 ## Key differences from OpenSpec
 
@@ -154,7 +158,7 @@ Results are deterministic, explainable, and debuggable. No embedding service req
 | Storage | Fixed filesystem directories | Typed markdown vault with frontmatter + wikilinks |
 | Canonical spec | `spec.md` file | `Feature` note with `## Requirements` section |
 | Identity | Filepath/filename | Immutable `id` in frontmatter (survives rename/move) |
-| Similarity detection | Free-form LLM reasoning | Deterministic retrieval subagent with scored signals |
+| Similarity detection | Free-form LLM reasoning | Deterministic retrieval + semantic embedding (multilingual) |
 | Pre-investigation | Prompt-driven, varies by session | Mandatory preflight scan before `propose` |
 | Note relationships | Directory nesting | Typed graph: wikilinks, backlinks, frontmatter links |
 | Completion model | Archive-first file movement | Status lifecycle + deferred archive |
@@ -287,10 +291,61 @@ See the full migration guide (available in `docs/migration.md` when building fro
   - Propose | Continue | Apply
   - Verify | Query | CLI Init
 
+## Full lifecycle example
+
+```bash
+# 1. Initialize
+ows init
+
+# 2. Propose a change (preflight retrieval runs automatically)
+ows propose "Add user authentication with email/password" --keywords "auth,login,password"
+
+# 3. Fill in the Change sections (Why, Delta Summary, Tasks, Validation)
+#    Then advance through the lifecycle:
+ows continue <changeId>          # proposed → planned
+ows continue <changeId>          # planned → in_progress
+
+# 4. Complete tasks, then apply to canonical Feature
+ows apply <changeId>
+
+# 5. Fill in any ADDED/MODIFIED markers in the Feature note
+#    Then verify everything is consistent
+ows verify
+
+# 6. Archive the completed change
+ows archive <changeId>
+```
+
 ## Requirements
 
 - Node.js >= 20.0.0
 
+## Contributing
+
+**We actively welcome contributions!** Whether it's bug reports, feature ideas, documentation improvements, or code — all forms of participation are appreciated.
+
+- **Issues**: Found a bug or have a suggestion? [Open an issue](https://github.com/sh940701/open-wiki-spec/issues).
+- **Pull Requests**: Fork the repo, make your changes, and submit a PR. We review promptly.
+- **Discussions**: Questions about architecture, design decisions, or use cases? Start a discussion in Issues.
+
+### Getting started for contributors
+
+```bash
+git clone https://github.com/sh940701/open-wiki-spec.git
+cd open-wiki-spec
+npm install
+npm run build
+npm test          # 805+ tests should pass
+```
+
+### Areas where help is especially welcome
+
+- **Semantic search improvements** — better embedding models, multilingual support
+- **Obsidian plugin** — native Obsidian integration for graph view, Dataview queries
+- **Additional agent runtime support** — Cursor, Codex, Gemini CLI adapters
+- **Documentation** — tutorials, examples, translations
+- **Testing** — edge cases, performance benchmarks, real-world usage reports
+
 ## License
 
 [MIT](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-wiki-spec",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Obsidian-first wiki workflow engine for specification management",
   "type": "module",
   "bin": {