Knowns Project Context Layer

The Web UI provides a visual alternative to CLI output for several core Knowns functions:

• Board and task views: Inspect active work, status, priorities, acceptance criteria, and notes.
• Docs browser: Read project documentation without needing to navigate CLI paths.
• Graph / knowledge views: Explore the relationships between tasks, docs, memory, and references.
• Configuration pages: Inspect project settings, search setup, code intelligence, and integration state.

Knowns generates Task IDs using a prefix and a 6-character suffix.

• Default behavior: If no prefix is configured, IDs are lowercase (e.g., 4f7q2m).
• Configured prefix: If a prefix is set via settings.defaultTaskIdPrefix (e.g., KN), IDs follow the format PREFIX-SUFFIX (e.g., KN-4F7Q2M).
• Overriding prefix: You can provide a prefix when creating a task via MCP to override the project default for that specific task without changing global settings. The prefix must be 2-8 alphanumeric characters starting with a letter and is normalized to uppercase.

Note: Changing the project default via CLI only affects tasks created after the change. Existing IDs remain valid.

Configure default prefix via CLI

knowns config get settings.defaultTaskIdPrefix --plain
knowns config set settings.defaultTaskIdPrefix KN

The OPENCODE.md file serves as a compatibility entrypoint for runtimes that automatically detect this file.

Important: This file is not the primary source of truth. You must always read and follow KNOWNS.md in the repository root, as it is the canonical source of truth for all agent behavior. If instructions in OPENCODE.md conflict with KNOWNS.md, follow KNOWNS.md.

Knowns acts as a project context layer that synchronizes state across the CLI, MCP server, and Web UI. The model consists of five interconnected parts:

• tasks: For planned work, status, acceptance criteria, implementation plans, and notes.
• docs: For durable project knowledge (architecture, specs, decisions, onboarding).
• memory: For short, reusable context (team conventions, assistant preferences).
• templates: For repeated project scaffolding.
• search / retrieval: For finding relevant context for humans or AI agents.

Knowns uses a file-based source of truth rather than a central database. All project knowledge—tasks, docs, decisions, memory, and templates—is stored as Markdown files with YAML frontmatter directly on your disk.

This approach ensures that your knowledge is:

• Human-readable: Viewable in any text editor.
• Version-controllable: Can be diffed in pull requests and recovered via Git.
• AI-ready: Provides clean context for LLMs.

Note on the Search Index: While the records are Markdown, Knowns maintains a derived SQLite index in .knowns/.search/ to enable fast searching. This directory is a cache and is safe to delete; you can rebuild it using knowns search index.

---
id: KN-4F7Q2M
title: Add JWT authentication
status: in-progress
priority: high
---

## Description

We need JWT auth because sessions do not scale across services.

Findings from a kn-review are classified into three severity levels to determine if a commit is allowed:

Calibration Rule: Avoid severity inflation. If you are unsure of the severity, default to P2.

The Web UI is the human-facing view of the project context and is not a replacement for the Model Context Protocol (MCP) interface used by AI assistants.

• AI Assistants: Should continue to use MCP initial to start and help for workflow/tool details.
• Humans: Should use the Web UI when they want to visually inspect or edit context, explore graphs, or use board-oriented task views.

If a task is linked to a spec, verify each deliverable across three levels of completeness:

1. EXISTS (L1): The file, component, or route exists.
2. SUBSTANTIVE (L2): The implementation is not a stub (e.g., no return null, empty handlers, or TODO only).
3. WIRED (L3): The code is imported and actively used in the integration layer.

Reporting Status:

• ✅ L1+L2+L3: Fully wired.
• ⚠️ L1+L2 only: Created but not integrated ($\rightarrow$ P2).
• 🛑 L1 only (stub): Exists but empty ($\rightarrow$ P1).
• 🛑 Missing: Not found ($\rightarrow$ P1).

Decide how much control you want over the implementation process:

• Use kn-flow for an orchestrated, end-to-end workflow. It handles task discovery, planning, implementation, and review automatically. In Codex, $kn-flow may use sub-agents for parallel tasks; use --sequential to force all work through the main context.
• Use kn-plan + kn-implement when you want manual control. This is useful if the spec is still evolving or if you want to inspect and adjust each individual task before any code is written.

Manual Task-Only Path Example:

1. Generate tasks from a spec: /kn-plan --from @doc/specs/user-auth
2. Execute a specific task: /kn-implement <TASK_ID> (e.g., /kn-implement KN-4F7Q2M)

# Manual path
/kn-plan --from @doc/specs/user-auth
/kn-implement KN-4F7Q2M