@svashevchenko/ez-know 0.1.0

package/dist/guides/business-rules.md

@@ -0,0 +1,47 @@
+# Business Rules
+
+Business rules describe observable AS-IS system behavior and product rules.
+
+A BusinessRule is not a Feature, Capability, or Constraint.
+
+## What To Capture
+
+- The condition that triggers the behavior.
+- The system response, restriction, or enforcement.
+- The feature, entity, or domain the rule applies to.
+- Whether the behavior is shown, hidden, rejected, transitioned, calculated, required, or allowed.
+
+## Style
+
+Prefer `when ... then ...` or Gherkin-compatible wording:
+
+```text
+WHEN <condition/context>
+THEN <expected system behavior/effect>
+```
+
+```text
+GIVEN <state/context>
+WHEN <event/action>
+THEN <observable outcome>
+```
+
+Examples:
+
+```text
+Paid orders cannot be cancelled directly.
+Only managers can approve invoices above $10,000.
+Refund amount is calculated from paid amount minus non-refundable fees.
+Cancel button is hidden when order status is Completed.
+An order must contain at least one item before submission.
+```
+
+## Rules
+
+- Capture behavior, not grouping.
+- Do not use BusinessRule for a high-level capability area.
+- Do not use BusinessRule as a replacement for Feature.
+- Prefer rules with explicit condition and effect.
+- If evidence only shows UI behavior, do not claim backend enforcement unless supported.
+- If the rule reason is unknown, create a Rationale with low confidence or a Question.
+- If a limitation is caused by implementation, integration, infrastructure, scale, or legacy architecture, capture that as Constraint instead of BusinessRule, or link both when the system behavior is caused by a constraint.

package/dist/guides/capabilities.md

@@ -0,0 +1,41 @@
+# Capabilities
+
+Capabilities are grouping containers for related features, similar to an Agile epic.
+
+Use capabilities when one domain or entity has too many related features and the grouping adds clarity.
+
+## What To Capture
+
+- The broader product area the feature set belongs to.
+- Domain and entity context.
+- Child features that belong in the same grouping.
+
+## Naming Guidance
+
+Good capability names:
+
+```text
+Order Management
+Order Lifecycle
+Refund Management
+Billing
+User Administration
+```
+
+Bad capability names:
+
+```text
+Create Order
+Cancel Order
+Approve Refund
+Generate Invoice
+```
+
+## Rules
+
+- Capability groups Feature objects.
+- Capability may group nested Capability objects if the area is large.
+- Capability must not be used as an atomic business function.
+- Capability should not be created only because a technical folder or module exists.
+- Capability can reference evidence that supports the grouping, but it should not become a code map.
+- If unsure whether something is Capability or Feature, ask: “Is this a concrete business action?” If yes, use Feature.

package/dist/guides/conflicts.md

@@ -0,0 +1,16 @@
+# Conflicts
+
+Conflicts record incompatible interpretations that evidence has not resolved.
+
+## What To Capture
+
+- The competing meanings or boundaries.
+- The evidence that supports each side.
+- The question that would resolve the conflict.
+
+## Guidance
+
+- Use Conflict instead of silently collapsing uncertain meanings.
+- Keep the conflict small and explicit.
+- Resolve it only when evidence or human input settles the ambiguity.
+- Create a Conflict when two records may represent the same concept but evidence is not strong enough to merge them.

package/dist/guides/constraints.md

@@ -0,0 +1,35 @@
+# Constraints
+
+Constraints describe limitations, boundaries, restrictions, or external forces that shape what the system can do or how it can do it.
+
+## What To Capture
+
+- The source of the limitation.
+- The effect on behavior, implementation, or planning.
+- Any workaround or removability clues.
+
+## When To Use
+
+Use Constraint when the important knowledge is:
+
+```text
+The system is limited by <cause/source>, which affects <feature/rule/entity/change>.
+```
+
+Examples:
+
+```text
+Username length is limited to 32 characters because the legacy database column is VARCHAR(32).
+Refund export is limited to 1000 records per batch because the ERP endpoint times out on larger payloads.
+Invoices must be retained for 7 years because of accounting regulation.
+Orders cannot be edited after ERP synchronization because the ERP integration is one-way.
+Only CSV export is available because the reporting pipeline does not support XLSX generation.
+```
+
+## Rules
+
+- Capture constraints as causes, boundaries, or limitations, not as generic behavior.
+- If the observable behavior is important, create a BusinessRule and link it to the Constraint.
+- If the source of the limitation is unknown, use `constraint_type: unknown` and create a Question.
+- Do not duplicate every BusinessRule as a Constraint. Create a Constraint only when there is a distinct limiting factor, cause, boundary, or implementation/compliance pressure.
+- Technical constraints are especially important for brownfield change planning because they identify why a seemingly simple product change may be hard.

package/dist/guides/domains.md

@@ -0,0 +1,17 @@
+# Domains
+
+Domains are the top-level product areas that own the rest of the knowledge graph.
+
+## What To Capture
+
+- The domain name and purpose.
+- Why the domain exists in the product.
+- The entities and capabilities that belong to it.
+- Evidence that shows this is a real product boundary, not just a folder boundary.
+
+## Guidance
+
+- Top-level grouping is always by domain.
+- Use one domain record per owning area.
+- If a concept crosses domains, keep one owner and reference it from the others.
+- Do not create domain records just because the codebase has a directory or module.

package/dist/guides/entities.md

@@ -0,0 +1,44 @@
+# Entities
+
+Entities are the product concepts the system stores, displays, validates, processes, or uses in business behavior.
+
+Entities also own the terminology related to them.
+
+## Use Entities For
+
+Use Entity for concepts such as:
+
+```text
+Order
+Invoice
+Customer
+Payment
+Refund
+Subscription
+User Account
+```
+
+Do not use Entity for purely technical implementation objects unless they represent a product concept visible in business behavior.
+
+## What To Capture
+
+- Canonical business meaning.
+- Aliases and ambiguous terms.
+- Technical representations only when they clarify the business concept.
+- Links to domains, relationships, capabilities, features, and rules.
+
+## Terminology Guidance
+
+- `name` is the canonical product name used by the knowledge base.
+- `business_definition` explains what the concept means in the product/domain.
+- `aliases` are alternative names used in UI, API, docs, translations, or code.
+- `ambiguous_terms` captures terms that may mean different things across domains.
+- `technical_representations` captures relevant code/API/database names without turning Entity into a code map.
+
+If the same term appears to mean different things in different domains, create separate Entity objects and a Conflict instead of forcing one meaning.
+
+## Guidance
+
+- Do not turn Entity into a code map.
+- Split meanings when the same term is used differently in different domains.
+- Prefer one entity with evidence over multiple near-duplicates.

package/dist/guides/evidence.md

@@ -0,0 +1,16 @@
+# Evidence
+
+Evidence is the central object of the knowledge base.
+
+## What To Capture
+
+- A short description of what the source proves.
+- The source type and location hint.
+- The objects that the evidence supports.
+
+## Rules
+
+- Do not store large code blocks.
+- Keep excerpts short.
+- Use evidence as support for product knowledge, not as a code index.
+- Human confirmation is valid evidence.

package/dist/guides/features.md

@@ -0,0 +1,43 @@
+# Features
+
+Features are the atomic business functions of the system.
+
+A Feature answers the question: what concrete business action can the system perform or support?
+
+## Good Feature Names
+
+```text
+Create Order
+Cancel Order
+Approve Refund
+Generate Invoice
+Reset Password
+Export Orders
+```
+
+Bad feature names:
+
+```text
+Order Management
+Billing
+Refund Area
+Admin Module
+```
+
+## Rules
+
+- Feature represents one concrete business action or user-visible business function.
+- Feature must not be used to group other features. Use Capability for grouping.
+- Feature can belong to one or more Capability objects.
+- Feature can be related to multiple Entity objects.
+- Feature can have BusinessRule and Constraint objects.
+- Feature must have evidence.
+- Feature should be independent from technical implementation details such as components, hooks, files, or services.
+- Avoid creating a feature for every tiny UI action unless the action has product meaning.
+
+## Decision Rule
+
+```text
+If it is a concrete action: Feature.
+If it is a grouping area for related actions: Capability.
+```

package/dist/guides/questions.md

@@ -0,0 +1,17 @@
+# Questions
+
+Questions are first-class artifacts.
+Questions capture important unknowns that block confident extraction or planning.
+
+## What To Capture
+
+- The exact unresolved question.
+- Why it matters for extraction or planning.
+- Related rules, constraints, or entities.
+
+## Guidance
+
+- Ask a question when confidence is too low to commit.
+- Keep questions specific and answerable.
+- Mark them obsolete or answered once the uncertainty clears.
+- Generate questions for all low-confidence or inferred important knowledge.

package/dist/guides/rationales.md

@@ -0,0 +1,17 @@
+# Rationales
+
+Rationale is the "why" layer.
+
+## What To Capture
+
+- The inferred reason behind the behavior.
+- The rule or constraint it explains.
+- Any evidence that supports the inference.
+
+## Guidance
+
+- Keep rationale language cautious.
+- If the reason is not explicit, treat it as inferred.
+- Do not duplicate the rule itself; explain it.
+- For every rule or constraint, attempt to explain why it likely exists.
+- If not explicit, mark it as inferred and generate a question.

package/dist/guides/relationships.md

@@ -0,0 +1,19 @@
+# Relationships
+
+Relationships describe how two entities connect or depend on each other.
+
+## What To Capture
+
+- The source entity and target entity.
+- The relationship type.
+- The observable description of the connection.
+- Evidence that supports both ends of the relationship.
+
+## Guidance
+
+- Use relationships for explicit links, ownership, containment, dependency, references, or transitions.
+- Use `depends_on` when the source object requires the target for runtime delivery of its visible behavior.
+- Use `references` when the source object can point to, display, or project the target without requiring it to function.
+- For cross-scope delivery paths, prefer a relationship when the external provider is necessary for the observable behavior to work.
+- Do not use them to restate a feature or rule.
+- Keep the wording factual and narrow.