# Knowledge Directory — Guide

## What is this?

The packaged `knowledge/` directory teaches the AI about the Fluent Commerce platform. Project-specific rules, conventions, and client details belong in `accounts/<PROFILE>/knowledge/`. Without both layers, the AI guesses. With them, it follows your platform and account patterns from the first interaction.

> **See also:** [DATA-ARCHITECTURE.md](DATA-ARCHITECTURE.md) — full guide to the three-layer data system (knowledge vs memory vs skills), with format specs, examples, and decision rules for what goes where.

## How to set it up

**You don't write these files.** The AI writes them. You just talk.

### Option 1: Quick wizard (20 minutes)

```
/fluent-knowledge-init
```

The AI asks 10-15 plain-English questions, then writes the files for you.

### Option 2: Drop existing docs

Drop a PDF, scope doc, or Confluence export and say:

> "Extract project knowledge from this"

The AI reads it, shows you what it found, and writes the files after you confirm.

### Option 3: Let it build up

Just work normally. When you correct the AI ("no, we name locations like LOC_SYD_STORE_01"), it captures that into the right knowledge file. After 3-5 sessions, you'll have solid coverage.

## Directory structure

```text
knowledge/
├── index.md                    # Packaged registry for universal platform docs
├── GUIDELINES.md               # This file
├── platform/                   # Fluent Commerce platform knowledge (shared across ALL accounts)
├── frontend/                   # Mystique SDK reference and UI patterns
└── templates/                  # Reusable templates shipped with the package

accounts/<PROFILE>/knowledge/
├── index.md                    # Account-specific registry and status
├── naming-conventions.md       # Entity refs, attribute names, rule class names
├── coding-standards.md         # Java/workflow/manifest/deployment conventions
├── client/
│   ├── business-rules.md       # Routing, constraints, exceptions, SLAs
│   ├── data-model.md           # Entity types, attributes, catalogues
│   ├── integrations.md         # External systems, APIs, data flows
│   └── test-data.md            # Test locations, products, customers
└── templates/                  # Account-specific plan/spec/deploy addenda
```

## What each file does

| File | AI uses it for | Priority |
|------|---------------|----------|
| **platform/domain-model.md** | Entity relationships, GraphQL edges, cross-domain maps, orchestrable vs non-orchestrable | Pre-populated (schema-validated) |
| **naming-conventions.md** | Naming everything it creates — entity refs, rule classes, settings keys | Set up first |
| **coding-standards.md** | Java code style, workflow structure, deployment process | Set up first |
| **business-rules.md** | Routing logic, constraints, exception handling in workflows and rules | Set up second |
| **data-model.md** | Entity types, subtypes, attributes, catalogue refs | Set up second |
| **integrations.md** | Rules that call external systems, webhook settings | Set up when relevant |
| **test-data.md** | Test payloads, E2E test scenarios, entity refs for testing | Set up when testing |

## How skills use knowledge

Every skill with a **"Pre-flight: Project Knowledge Check"** section reads packaged platform docs before starting, then layers account-specific knowledge on top:

1. Skill reads the packaged platform docs it needs from `knowledge/`
2. Skill reads matching account files from `accounts/<PROFILE>/knowledge/` when `FLUENT_PROFILE` is set
3. Skill may also read `accounts/<PROFILE>/memory/index.md` for account-specific gotchas
4. Account-level knowledge in `accounts/<PROFILE>/knowledge/` takes precedence over packaged platform defaults

### Skills with knowledge pre-flight

| Skill | Reads domain-model | Reads partner | Reads client | Status |
|-------|-------------------|---------------|-------------|--------|
| `/fluent-feature-plan` | Yes | naming + coding | business-rules + data-model + integrations | Active |
| `/fluent-workflow-builder` | Yes | naming + coding | business-rules + data-model | Active |
| `/fluent-rule-scaffold` | Yes | naming + coding | business-rules + integrations | Active |
| `/fluent-settings` | Yes | naming | data-model + integrations | Active |
| `/fluent-use-case-discover` | Yes | — | business-rules + integrations + data-model | Active |
| `/fluent-mystique-builder` | Yes | naming | data-model | Active |
| `/fluent-custom-code` | Yes | coding | business-rules + integrations | Active |
| `/fluent-trace` | Yes | — | data-model | Active |
| `/fluent-implementation-map` | Yes | — | business-rules + data-model | Active |
| `/fluent-feature-explain` | Yes | — | business-rules + data-model | Active |
| `/fluent-connection-analysis` | Yes | — | data-model | Active |
| `/fluent-scope-decompose` | Yes | — | business-rules + data-model | Active |

You don't need to tell the AI "check my knowledge files" — it does it automatically.

## How to verify skills are loading knowledge

### Method 1: Ask the AI directly

After invoking any skill, ask:

> "What knowledge files did you load during pre-flight?"

The AI will list which files it read and what it extracted.

### Method 2: Check the pre-flight output

Skills that load knowledge will mention it in their execution trace. Look for lines like:
- "Pre-flight: loaded domain-model.md (9 domains, 40+ entities)"
- "Pre-flight: loaded naming-conventions.md (ref patterns, class naming)"
- "Pre-flight: no knowledge files found — using defaults"

### Method 3: Test with a known convention

1. Add a distinctive naming rule to `accounts/<PROFILE>/knowledge/naming-conventions.md`, e.g.:
   > "All order refs must start with `TEST-ORD-`"
2. Run `/fluent-workflow-builder` or `/fluent-rule-scaffold`
3. Check if the generated artifacts follow your naming rule
4. If they do, knowledge is being loaded. If not, check `accounts/<PROFILE>/knowledge/index.md`.

### Method 4: Check index.md registration

Open `accounts/<PROFILE>/knowledge/index.md` and verify:
- The file is listed in the table
- `relevant-skills` includes the skill you're testing
- Status shows "Active" (not "Template")

## Platform knowledge (pre-populated)

The `platform/` directory contains Fluent Commerce platform knowledge that applies to ALL projects:

- **`domain-model.md`** — All 9 business domains, 40+ entity types, every GraphQL edge validated against the live schema. Includes orchestrable/non-orchestrable classification, cross-domain relationship map, and 13 key schema gotchas. Skills use this to understand entity traversal paths, valid connections, and relationship constraints.

This file is schema-validated (not hand-written) and should be updated when Fluent releases new entity types or changes the GraphQL schema.

## Tips

- **Be specific**: "Order refs: `ORD-{storeCode}-{date}-{seq}`" is useful. "We have naming conventions" is not.
- **Include examples**: Every rule should have at least one concrete example.
- **Say WHY**: "Warehouse-first because 80% ships from 2 DCs" helps the AI make better tradeoff decisions.
- **Keep files under 200 lines**: If a file gets too long, split it into sub-topics.
- **Review what the AI writes**: The AI always confirms before writing. If something's wrong, say so.

## Account-specific overrides

If you have multiple retailers/accounts, put account-specific knowledge in:

```
accounts/<PROFILE>/knowledge/
├── naming-conventions.md   # Naming rules specific to THIS account
├── coding-standards.md     # Build, workflow, and deployment conventions
└── client/
   ├── business-rules.md    # Rules specific to THIS account
   └── test-data.md         # Test data for THIS environment
```

Account-level files take precedence over packaged platform knowledge.
