CKL Explained

What is CKL?

The Compliance Knowledge Layer (CKL) is a separate retrieval system that enriches Planara's responses with industry standards, regulations, and safety best practices. It exists alongside the main document index but serves a different purpose.

Main document index: "Here is how to do the procedure" CKL: "Here are the safety standards and regulations relevant to this procedure"

Architecture

Main Index                      CKL Index
├── Service manual content     ├── ABYC E-11 (electrical)
├── Owner's manual content     ├── ABYC H-2 (ventilation)
├── Parts catalog content      ├── Corrosion best practices
└── TSB content                └── Custom safety rules

Both indexes are searched, but CKL is only activated when trigger terms match.

Trigger mechanism

CKL activation follows this decision tree:

1. Query arrives (e.g., "How do I check the sacrificial anodes?")
2. Main retrieval runs normally
3. Query text and retrieved documentation are scanned for trigger terms
4. If any trigger matches (e.g., "anode" matches trigger "anode"), CKL search runs
5. CKL sources above the relevance threshold are included as generation context
6. The AI generates the response with CKL citations

Trigger terms

Comma-separated keywords configured on the CKL page. Examples:

• corrosion, galvanic, anode, zinc
• ABYC, electrical, grounding, bonding
• fuel system, ventilation, blower

Thresholds

Sources

CKL sources come from two places:

1. Manual entries

Text-based knowledge added directly on the CKL page. Each source has:

• A name and standard ID
• The actual content (indexed for semantic search)
• Topic tags
• An optional source URL

2. Ingested CKL documents

PDFs uploaded with the "CKL" document type. These are processed by the ingestion pipeline but stored in the CKL index instead of the main index.

How CKL appears in responses

Technician frontend

CKL citations appear as blue chips on procedure steps:

Step 3: Replace the sacrificial anodes
[ABYC E-11]  [CORR-BP-001]

Tapping a chip shows the source standard, relevant excerpt, and link.

API response

CKL references appear in the response schema as ckl_refs on procedure steps:

{
  "procedure": [
    {
      "step": "Replace the sacrificial anodes",
      "ckl_refs": [0, 2]
    }
  ]
}

Per-tenant isolation

Each namespace has its own CKL configuration:

• A marine tenant gets ABYC standards
• A factory tenant gets ISO/OSHA standards
• An HVAC tenant gets EPA and building code references

There is no cross-contamination between namespaces.

When to use CKL vs. main documents

Examples: trigger configs that work, and ones that don't

Triggers decide when CKL fires. Too narrow and the standard never surfaces. Too broad and every query drags in irrelevant standards and bloats the generation context.

Good configs

Specific terms, narrow scope, real synonyms a tech would actually type or that show up in the manual.

Standard:  ABYC E-11 (DC electrical systems)
Triggers:  battery, ground, bonding, ABYC E-11, DC wiring, shore power, GFCI

Standard:  ABYC H-24 (gasoline fuel systems)
Triggers:  fuel hose, fuel tank, fuel pump, vent, fill, USCG Type A1, anti-siphon

Standard:  Corrosion best practices
Triggers:  anode, zinc, sacrificial, galvanic, MGPS, bonding wire, stray current

Note: include both the formal term (galvanic) and what a tech actually writes (zinc). Include the standard ID (ABYC E-11) so direct lookups hit.

Common mistakes

Standard:  ABYC E-11
Triggers:  safety, electrical, wire     ← BAD

Fires on almost every procedure. Pollutes the generation context with E-11 even when the query is about a fuel filter. Use specific nouns from the standard's actual scope.

Standard:  ABYC E-11
Triggers:  battery, ground, bonding
Standard:  Corrosion best practices
Triggers:  battery, ground, bonding     ← BAD (duplicate)

Two standards on the same triggers means every battery query loads both. Pick the primary owner of each term, or split — e.g., E-11 owns battery, ground, bonding, corrosion owns anode, zinc, galvanic.

Standard:  ABYC H-24
Triggers:  fuel system     ← BAD (missing synonyms)

Misses gas, gasoline, fuel hose, fuel pump, vent. Real queries use those words, not the formal phrase.

Validate before you ship

The /[ns]/knowledge page doesn't run test queries directly — it edits trigger config, thresholds (confidence_threshold, relevance_threshold, top_k), and the standards list. To verify triggers fire correctly, you have to query the system end-to-end:

1. Save the trigger config on /[ns]/knowledge.
2. Run 5–10 real tech queries from the namespace — either through the technician app, or by hitting POST /v1/query directly with skip_cache=true.
3. Inspect each response's ckl_sources array. Anything firing on every query is too broad — narrow the triggers. Anything that doesn't fire when it should — add the missing synonym.
4. If you need a single-query check while iterating, the same POST /v1/query call with one trigger term in the query body will tell you whether the standard reaches generation at all.

Triggers are silent failures: nothing breaks, the answer just quietly stops citing the standard. Re-validate after every trigger or threshold change.