@svashevchenko/ez-know 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# ez-know
+!!! Important: early development stage !!!
+
+A business knowledge layer for your agents and your team.
+
+When do you need it?
+- You have a complex project with lots of entities, features and rules to govern them all;
+- Your agents break your apps when they miss some important spec;
+- Your team have a hard time answering questions like "Did we implement this right", "Does this feature conflict with our rule".
+
+## What's in the box
+
+- MCP server + agent skills 
+- REST server + UI for easy exploration and validation
+
+## What it gives you
+
+As a multiple products dev, I frequently need to 
+
+## How to run
+
+Install globally with `npm i -g ez-know`, then
+
+- `ez-know` for package overview and all important info
+- `ez-know init` prompts for a skills folder and installs the bundled reference skills there
+- `ez-know mcp` starts the MCP server over stdio
+- `ez-know rest` starts the REST service and serves the frontend UI
+
+`ez-know init` overwrites matching skill folder contents in the target directory, so rerunning it is safe when you want the bundled skills refreshed.
+
+For repo development:
+
+- `npm run dev` starts REST and web together
+- `npm run dev:rest` starts only REST
+- `npm run dev:web` starts only the web app
+
+Configuration
+
+| env| default | desc |
+|----|---|-----|
+|EZ_KNOW_ROOT| ez-know|path relative to PWD where you want to store knowledge data |
+|EZ_KNOW_REST_HOST| |host for the rest service|
+|EZ_KNOW_REST_PORT| |port for the rest service |
+
+## How does it work?
+
+
+DDD-discovery
+Knowledge engineering
+
+
+
+The built package also exposes the same runtime entrypoints through npm scripts:
+
+## Included Tools
+
+- `knowledge_graph_query` executes GraphQL queries against the normalized in-memory knowledge store.
+- `knowledge_patch` manages draft patches with create, list, get, add/update/delete operation, validate, and close actions.
+- `knowledge_patch_apply` mutates canonical knowledge JSON only after explicit approval plus the latest validation fingerprint.
+
+
+## Knowledge Patch Workflow
+
+Patch drafts live under `EZ_KNOW_ROOT/.patches/<patch-id>/` and contain only:
+
+- `patch.json` for patch metadata and lifecycle state
+- `operations.json` for the ordered semantic operations managed by the server
+
+Patch operations must use canonical collection names from the extraction registry such as `features`, `business_rules`, and `evidence`. Patch operations do not accept canonical file paths; the server derives target files from the collection type and domain during apply.
+
+Suggested flow:
+
+1. Call `knowledge_patch` with `action: "create"` to open a draft patch.
+2. Use `add_operation`, `update_operation`, and `delete_operation` to manage ordered semantic operations.
+3. Call `knowledge_patch` with `action: "validate"` and keep the returned `fingerprint`.
+4. Call `knowledge_patch_apply` with `approval.approved: true` and the latest validation fingerprint.
+
+Apply is rejected when approval is missing or false, when validation fails, when the fingerprint is stale, or when the patch is not the first pending draft in sequence. Successful apply rewrites the affected canonical JSON files, reloads the knowledge store from disk, and deletes the patch folder only after reload verification succeeds.
+
+Sequential pending patch semantics:
+
+- Normal MCP and REST reads use an effective state composed from canonical knowledge plus ordered draft patches.
+- Patch validation uses the same effective base state, excluding the patch currently being validated.
+- Draft ordering is deterministic: `createdAt`, then patch id as a tie-breaker.
+- Canonical JSON remains the persisted source of truth until explicit apply.
+- Later draft patches should be created with the expectation that earlier drafts are part of the current query and validation state.
+- Draft patches must also be applied in order: only the first pending draft can be applied.
+
+## Knowledge Root
+
+The server discovers domain folders under `EZ_KNOW_ROOT`, or `./ez-know` when the env var is omitted, loads the canonical JSON files from each domain folder, and combines the results into one in-memory knowledge store. The knowledge schema is defined in `src/reference/ez-know.d.ts` and includes domains, entities, relationships, capabilities, features, business rules, constraints, rationales, evidence, questions, and conflicts.