docs: subagent-driven workflow with knowledge base

docs/helpers/README.md

@@ -0,0 +1,46 @@
+# Knowledge Base (docs/helpers/)
+
+This directory is the project's persistent knowledge base, maintained by
+`coder` and `review` subagents (see `docs/workflow.md`).
+
+## Files
+
+- `faq.md` — frequently asked questions, recurring pitfalls and their
+  solutions (FFI memory leaks, `test_dbs/` cleanup, the `-n` flag, ...)
+- `decisions.md` — important decisions with rationale (API compatibility
+  with Node.js/Python SDKs, naming, intentional deviations)
+
+## Rules
+
+- **Read before starting** a task — the knowledge carries over between tasks.
+- **Append after finishing** — one topic, the problem, the
+  solution/decision, optionally an issue/commit reference.
+- Entries must be **short and actionable**. No essays.
+- In doubt whether an entry is worth keeping, ask the user.
+- New files may be added for a new topic area, but keep the structure flat:
+  one FAQ file, one decisions file, or a topic file only when a category
+  grows large (e.g. `ffi-memory.md`).
+
+## Entry template (faq.md)
+
+```markdown
+### Topic title
+
+**Problem:** one sentence — what breaks / what people trip on.
+
+**Solution:** one or two sentences — the correct approach.
+
+**Reference:** optional (issue/commit/task number).
+```
+
+## Entry template (decisions.md)
+
+```markdown
+### Decision title
+
+**Decision:** what was decided (API shape, naming, deviation).
+
+**Rationale:** why — reference implementation, constraint, past bug.
+
+**Reference:** optional (issue/commit/task number).
+```

docs/helpers/decisions.md

@@ -0,0 +1,52 @@
+# Decisions — Important Choices & Rationale
+
+Knowledge base maintained by `coder`/`review` subagents. Read before
+starting a task, append after finishing. See `README.md` for rules.
+
+---
+
+### Enum values must match Node.js / Python SDKs
+
+**Decision:** PHP constants use identical values to the official SDKs
+(e.g. `QUANTIZE_INT8 = 2`, `METRIC_IP`, `TYPE_FLOAT = 8`).
+
+**Rationale:** keeps the PHP API compatible across languages; the Node.js
+API, Python SDK and C++ headers are the reference implementations.
+
+---
+
+### PHP 8.1+ with full type declarations
+
+**Decision:** all properties, parameters and return types are fully typed;
+union types (`FFI\CData|string`) and PHPDoc only where PHP's type system
+is insufficient (array generics).
+
+**Rationale:** safety and self-documenting code; no redundant PHPDoc.
+
+---
+
+### FFI declarations inline in `FFI::cdef()`
+
+**Decision:** inline C declarations in `FFI::cdef()` — never load the `.h`
+file at runtime.
+
+**Rationale:** no runtime dependency on header paths.
+
+---
+
+### Global classes via Composer classmap
+
+**Decision:** global classes (`ZVec`, `ZVecSchema`, `ZVecDoc`, ...) are
+loaded via Composer classmap autoloading; `src/ZVec.php` is a barrel file
+for backward compatibility with `require_once`.
+
+---
+
+### Alter column: scalar numeric types only, nullable never turns off
+
+**Decision:** `alterColumn()` supports renaming and type change for scalar
+numeric types only; `nullable: true → false` is not supported; rename and
+type change cannot be combined in one call.
+
+**Rationale:** limitation of the underlying C++ layer — verify in
+`zvec/src/include/zvec/db/` before extending.

docs/helpers/faq.md

@@ -0,0 +1,60 @@
+# FAQ — Recurring Pitfalls & Solutions
+
+Knowledge base maintained by `coder`/`review` subagents. Read before
+starting a task, append after finishing. See `README.md` for rules.
+
+---
+
+### Run tests with `-n` (no php.ini)
+
+**Problem:** a legacy pre-installed `zvec` PHP extension (v0.4.10) in
+`php.ini` shadows the FFI classes (`src/ZVec.php` bails out early), so FFI
+classes like `ZVecIndexParams` never load and tests fail en masse.
+
+**Solution:** always run the suite as
+`php run-tests.php -n tests/` — the `-n` flag disables the extension.
+
+**Reference:** issue #188.
+
+---
+
+### `run-tests.php` deletes legacy `tests/*.php` files
+
+**Problem:** `run-tests.php` derives the executable path from the `.phpt`
+basename and unlinks it unconditionally — legacy tracked
+`tests/<name>.php` files sharing a basename with a `.phpt` file get
+deleted.
+
+**Solution:** back them up first, or restore with
+`git checkout -- tests/` after the run. Note the restore also reverts
+local edits — keep fixes re-applied.
+
+**Reference:** issue #187.
+
+---
+
+### Always call `optimize()` before performance testing
+
+**Problem:** after inserting docs, `index_completeness: 0` — queries work
+but fall back to brute-force scan.
+
+**Solution:** call `optimize()` before performance tests.
+
+---
+
+### Free C strings and follow status checks
+
+**Problem:** memory leaks in FFI bindings.
+
+**Solution:** always convert with `FFI::string($ptr)` and `FFI::free($ptr)`;
+never store `FFI\CData` in long-lived variables; check status after every
+FFI call via `self::checkStatus()`.
+
+---
+
+### `destroy()` invalidates the handle
+
+**Problem:** after `destroy()` any method call segfaults.
+
+**Solution:** only `close()` if the collection may be reopened; never use
+an object after `destroy()`.