# Wisdom, vector knowledge, graph context, and prompts

Kiduna currently has two related but distinct knowledge domains. The new UI should name and scope them clearly rather than treating every vector store as one undifferentiated “Knowledge” page.

## Agent wisdom / knowledge bases (`kinship-agent-be`)

- List knowledge bases by wallet/platform and inspect a knowledge base.
- Create, rename/update, and delete a knowledge base.
- Upload supported files; parse file content; reject unsupported/invalid files.
- Add raw text directly (`dev` includes a dedicated `ingest-text` action).
- Create item records, chunk content, generate embeddings, ingest/re-ingest an item, and remove an item.
- Search a knowledge base semantically and return matched chunks/sources.
- Attach multiple knowledge bases to Presence and worker agents.
- Connect a knowledge base to a prompt.
- Import from Google Drive picker or folder URL through the frontend proxy.
- Show ingestion status, item count, source/file metadata, errors, and deletion progress.
- `main` includes Pinecone service evidence; `dev` migrates agent KB chunks to PostgreSQL `pgvector`, adds lifecycle/listener services, and removes the Pinecone agent store.

## Agent/member/governance graph

- Health-check graph storage.
- Synchronize agents, members, governance, or all graph domains.
- Accept single or batch graph events (`dev`).
- Extract graph content and relationships from operational data.
- Retrieve related people, agents, contexts, roles, governance items, and content.
- Perform guarded Cypher/graph queries with visibility, membership, and governance constraints.
- Feed graph retrieval into agent tools and supervisor context.
- Surface sync time, freshness, source, entity/edge counts, failed events, retry, and visibility reason.

## Game knowledge (`kinship-knowledge`)

- CRUD knowledge records used by games/scenes/NPCs.
- Ingest a new or existing record into the game-generation vector index.
- Embed and sync asset knowledge; embed only assets; rebuild/clear the index; remove one asset; inspect an asset embedding.
- List vector/index status, knowledge documents, embedded assets, and generated design knowledge.
- Test retrieval and inspect matches.
- Generate/regenerate design knowledge and asset knowledge individually or in bulk.
- Report asset-knowledge coverage and synchronize results back to the asset service.
- Use retrieval in game planning, mechanic matching, scene generation, NPC/dialogue generation, and validation.

## Prompts and instructions

- Prompt tiers: global (1), scene (2), and NPC (3).
- List/filter prompts by wallet, platform, tier, status, and category.
- Create, inspect, edit/replace, activate/deactivate, and delete a prompt.
- Configure name, content, description, category, tone, persona, audience, output format, goal, platform ownership, and connected knowledge base.
- Validate whether a goal is sufficiently clear.
- AI-generate system-prompt content from guidance fields and custom instructions.
- Manage global prompts, guardian prompts, and scene-type prompts in Studio.
- Add scene-level system prompts and platform/project instruction text plus instruction IDs.
- Assemble prompt layers for generation/runtime: platform/project instructions, global/scene/NPC prompt, retrieved knowledge, player/context state, and safety/validation guidance.

## Required knowledge-state design

Every knowledge item needs visible states for queued, parsing, chunking, embedding, indexed, stale, failed, re-ingesting, and deleted. The user must be able to identify:

- ownership and scope;
- source (file, Drive, text, generated, graph, asset service);
- vector engine/index and last synchronization;
- which agents/prompts/platforms/projects/games use it;
- whether deleting or replacing it will break dependents;
- search/retrieval quality and citations;
- storage/usage/cost impact;
- permissions and public/private/secret visibility.

## New UI gap

The v1 screens represent list/create/upload/ingest/edit/detail flows, but do not provide a complete operational surface for vector backend status, graph synchronization/events, dependency impact, retrieval evaluation, re-indexing, cost/usage, or cross-system distinction. These are mandatory additions or intentional admin-only decisions.

