docs: add CONTRIBUTING, issue templates, ROADMAP, tutorial (6 steps)

Author: miaobyte

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Report a bug in kvlang
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+### Describe the bug
+A clear description of the issue.
+
+### To Reproduce
+```kvlang
+// minimal .kv code that triggers the bug
+```
+
+```bash
+# command to reproduce
+```
+
+### Expected behavior
+What should happen.
+
+### Actual behavior
+What happens instead (error message, wrong output, crash).
+
+### Environment
+- OS: [e.g. Ubuntu 24.04]
+- Go version: [e.g. 1.24.4]
+- Redis version: [e.g. 7.2]
+- kvlang commit: [e.g. v0.1.0]

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea for kvlang
+title: "[FEAT] "
+labels: enhancement
+assignees: ""
+---
+
+### Problem
+What problem does this feature solve?
+
+### Proposal
+Describe the feature. If applicable, include kvlang pseudo-code.
+
+```kvlang
+// how the feature would look in kvlang
+```
+
+### Alternatives considered
+Other approaches you've thought about.
+
+### Additional context
+Links, references, or use cases.

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to kvlang
+
+Thanks for your interest! Here's how to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/array2d/kvlang.git
+cd kvlang
+make build
+```
+
+**Prerequisites**: Go 1.24+, Redis (for integration tests).
+
+## Development workflow
+
+```bash
+# After making changes:
+make vet          # static analysis
+make test         # unit tests
+python3 example/run.py    # integration tests (requires Redis)
+```
+
+## Project structure
+
+```
+cmd/kvlang/         CLI entry point
+internal/
+  parser/           .kv source → AST
+  lower/            control flow lowering (if/while → block + branch)
+  layoutcode/       AST → KV path tree (opcodes at /vthread/*)
+  vthread/          virtual thread lifecycle
+  kvcpu/            128-worker goroutine scheduler
+  kvspace/          KV storage abstraction (Redis backend)
+  vtype/            typed value system (int, float, bool, str, tensor)
+  op/
+    builtin/        native operators (arith, compare, logic, cast, call, io)
+    dispatch/       opcode → executor routing
+  device/           I/O device drivers (terminal, websocket)
+example/            .kv example programs + integration test runner
+doc/                design documents, specs, drafts
+```
+
+## Key concepts
+
+- **KV path addressing**: code and data share one tree. Instructions are paths. Call = subtree copy.
+- **vthread**: lightweight execution context. State stored as KV paths under `/vthread/<vtid>/`.
+- **typed values**: `kvspace.Value{kind, raw}` — kind maps directly to `vtype.VType.Name()`.
+
+## Commit conventions
+
+- `feat:` new feature
+- `fix:` bug fix
+- `refactor:` code restructuring
+- `docs:` documentation
+- `test:` test additions
+
+## Questions?
+
+Open an issue or start a discussion.

README.md

@@ -129,6 +129,25 @@ print("fib =", './result')    // → fib = 55
 
 ---
 
+## Tutorial
+
+Get started in 5 minutes with progressive examples:
+
+| Step | Topic | Code |
+|------|-------|------|
+| [01](tutorial/01-hello/main.kv) | Hello World | `print("hello kvlang")` |
+| [02](tutorial/02-vars/main.kv) | Variables | `42 -> './x'` |
+| [03](tutorial/03-arith/main.kv) | Arithmetic | `10 + 3`, `pow(2,5)`, `sqrt(144)` |
+| [04](tutorial/04-func/main.kv) | Functions | `def add(...)` |
+| [05](tutorial/05-if/main.kv) | Control Flow | `if (x < 0) { ... }` |
+| [06](tutorial/06-recursion/main.kv) | Recursion | `fib(10)`, `fact(10)` with TCO |
+
+```bash
+kvlang tutorial/01-hello/main.kv    # run any tutorial step
+```
+
+---
+
 ## Examples
 
 179 example programs, graded P0–P3:

ROADMAP.md

@@ -0,0 +1,40 @@
+# Roadmap
+
+## v0.1 (current) — Core VM
+
+- [x] KV path-addressed instruction model
+- [x] typed values: int, float, bool, str, bytes, tensor
+- [x] builtin operators: arith, compare, logic, cast, call, io
+- [x] TCO (tail-call optimization)
+- [x] vthread coroutine scheduler (128 workers)
+- [x] soft links (path redirection)
+- [x] serve daemon with Redis persistence
+- [x] pipe/inline execution modes
+
+## v0.2 — Developer Experience
+
+- [ ] structured tutorial (tutorial/)
+- [ ] playground / online demo
+- [ ] language server (LSP) for IDE support
+- [ ] improved error messages with source locations
+- [ ] `go install` support
+
+## v0.3 — Ecosystem
+
+- [ ] package manager (`kvlang get`)
+- [ ] standard library: http, json, file I/O
+- [ ] foreign function interface (FFI)
+- [ ] benchmarking suite
+
+## v0.4 — Distributed
+
+- [ ] multi-node vthread scheduling
+- [ ] kvspace sharding
+- [ ] RDMA backend for kvspace
+- [ ] cluster mode (`kvlang serve --cluster`)
+
+## Future
+
+- [ ] GPU tensor ops (via Triton)
+- [ ] WASM compile target
+- [ ] self-hosting compiler (kvlang → kvlang)

doc/kvlang/草稿/repo.md

@@ -19,17 +19,17 @@
 
 ### 改进项（按优先级）
 
-**P0 — 必须有**:
-- [ ] **添加 LICENSE**（MIT 或 Apache 2.0）。无 LICENSE 的开源项目 star 数天然打折。
-- [ ] **README 加英文版**（`README.md` → `README_CN.md`，新建 `README.md` 英文）。GitHub 默认流量是英文。
+**P0 — 已完成**:
+- [x] **添加 LICENSE**（MIT）
+- [x] **README 加英文版** + mermaid 架构图
+- [x] **GitHub Actions CI** + badge
+- [x] **打 tag v0.1.0** + CHANGELOG
 
-**P1 — 显著提升**:
-- [ ] **架构图**：一张 mermaid/svg 图展示 `kvlang → parser → layoutcode → lower → opcode → vthread → kvspace → Redis` 流水线
-- [ ] **5 分钟快速入门**：README 中一个完整可跑的 hello world（含预期输出）
-
-**P2 — 锦上添花**:
-- [ ] **语言规范独立文件**（`doc/LANGUAGE_SPEC.md`）：从 grammar.bnf 扩展出语义说明
-- [ ] **API 参考**：builtin 函数一览表
+**P1**:
+- [x] **CONTRIBUTING.md**
+- [x] **Issue 模板**（bug report + feature request）
+- [x] **ROADMAP.md**
+- [x] **5 分钟入门教程**（`tutorial/` 目录，6 步渐进）
 
 ---
 

tutorial/01-hello/main.kv

@@ -0,0 +1,5 @@
+// 01-hello: your first kvlang program
+// Run: kvlang tutorial/01-hello/main.kv
+
+str.set("kvlangrun") -> './term'   // activate output
+print("hello kvlang")

tutorial/02-vars/main.kv

@@ -0,0 +1,10 @@
+// 02-vars: variables and paths
+// Run: kvlang tutorial/02-vars/main.kv
+
+str.set("kvlangrun") -> './term'
+
+42 -> './x'                         // write 42 to path './x'
+print("x =", './x')                 // read from path './x'
+
+'./x' + 8 -> './y'                  // 42 + 8 = 50
+print("y =", './y')

tutorial/03-arith/main.kv

@@ -0,0 +1,17 @@
+// 03-arith: arithmetic operations
+// Run: kvlang tutorial/03-arith/main.kv
+
+str.set("kvlangrun") -> './term'
+
+print("add:", 10 + 3)              // 13
+print("sub:", 10 - 3)              // 7
+print("mul:", 10 * 3)              // 30
+print("div:", 10 / 3)              // 3 (int division)
+print("fdiv:", 10.0 / 3.0)        // 3.333...
+
+// math builtins
+print("pow:", pow(2, 5))           // 32
+print("sqrt:", sqrt(144))          // 12
+print("abs:", abs(-42))            // 42
+print("max:", max(3, 7, 1))        // 7
+print("min:", min(3, 7, 1))        // 1

tutorial/04-func/main.kv

@@ -0,0 +1,18 @@
+// 04-func: defining and calling functions
+// Run: kvlang tutorial/04-func/main.kv
+
+str.set("kvlangrun") -> './term'
+
+def add(A: int, B: int) -> (C: int) {
+    A + B -> './C'
+}
+
+def double(x: int) -> (y: int) {
+    x * 2 -> './y'
+}
+
+add(10, 20) -> './a'               // 30
+print("add(10,20) =", './a')
+
+double('./a') -> './b'              // 60
+print("double(add(10,20)) =", './b')