feat: save

Author: Rieranthony

apps/api/src/ai-agent/AI-README.md

@@ -46,17 +46,19 @@ The AI is NOT just a "replier" - it's a decision-making agent that chooses the b
 
 3. **Layered Security**: Immutable security prompts sandwich the user-configurable base prompt, preventing prompt injection attacks.
 
-4. **Behavior Settings**: Each AI agent can be configured with different capabilities and background analysis settings. Settings are persisted in the database and configurable via dashboard.
+4. **Prompt Governance**: `security.md` is immutable, `agent.md` is controlled by base prompt, and all other core policy docs are editable through prompt studio.
 
-5. **BullMQ Execution**: All processing happens in BullMQ workers for reliability and scalability.
+5. **Behavior Settings**: Each AI agent can be configured with different capabilities and background analysis settings. Settings are persisted in the database and configurable via dashboard.
 
-6. **Fast Response**: Queue delay is disabled; natural typing delays between messages keep responses human.
+6. **BullMQ Execution**: All processing happens in BullMQ workers for reliability and scalability.
 
-7. **Audience-Aware Events**: Progress events have audience filtering (widget vs dashboard) for appropriate visibility.
+7. **Fast Response**: Queue delay is disabled; natural typing delays between messages keep responses human.
 
-8. **Allowlist-Driven Tool Timeline Visibility**: Only allowlisted tools are treated as conversation-visible timeline activity; all other tools are persisted as log-only timeline rows.
+8. **Audience-Aware Events**: Progress events have audience filtering (widget vs dashboard) for appropriate visibility.
 
-9. **AI SDK v6-Compatible Tool Metadata**: Tool linkage and classification metadata is stored under `callProviderMetadata.cossistant.toolTimeline` (with backward-compatible `providerMetadata` support), with no new DB schema fields.
+9. **Allowlist-Driven Tool Timeline Visibility**: Only allowlisted tools are treated as conversation-visible timeline activity; all other tools are persisted as log-only timeline rows.
+
+10. **AI SDK v6-Compatible Tool Metadata**: Tool linkage and classification metadata is stored under `callProviderMetadata.cossistant.toolTimeline` (with backward-compatible `providerMetadata` support), with no new DB schema fields.
 
 ---
 
@@ -131,6 +133,8 @@ apps/api/src/ai-agent/
 │   ├── system.ts             # Dynamic system prompt (layered architecture)
 │   ├── security.ts           # Core security prompts (immutable)
 │   ├── templates.ts          # Reusable fragments
+│   ├── documents.ts          # Core/skill document naming and editability rules
+│   ├── resolver.ts           # Core + skill prompt resolution with overrides
 │   └── instructions.ts       # Behavior instructions
 │
 ├── tools/                    # LLM tools
@@ -153,7 +157,7 @@ apps/api/src/ai-agent/
 │   ├── categorization.ts     # Auto-categorize
 │   └── injection.ts          # Prompt injection detection
 │
-├── output/                   # Structured output
+├── output/                   # Output parsing utilities (tool-loop compatibility)
 │   ├── schemas.ts            # Zod schemas
 │   └── parser.ts             # Parse & validate
 │

apps/api/src/ai-agent/behaviors/catalog.ts

@@ -2,6 +2,7 @@ import type {
 	AiAgentBehaviorPromptDocumentName,
 	AiAgentBehaviorPromptId,
 	AiAgentBehaviorPromptPreset,
+	AiAgentEditableCorePromptDocumentName,
 } from "@cossistant/types";
 import { PROMPT_TEMPLATES } from "../prompts/templates";
 
@@ -14,6 +15,13 @@ export type BehaviorPromptDefinition = {
 	presets: readonly AiAgentBehaviorPromptPreset[];
 };
 
+export type CorePromptStudioDefinition = {
+	documentName: AiAgentEditableCorePromptDocumentName;
+	label: string;
+	description: string;
+	presets: readonly AiAgentBehaviorPromptPreset[];
+};
+
 const VISITOR_CONTACT_PRESETS = [
 	{
 		id: "contact_only_if_needed",
@@ -98,6 +106,52 @@ const BEHAVIOR_PROMPT_CATALOG = [
 	},
 ] as const satisfies readonly BehaviorPromptDefinition[];
 
+const EDITABLE_CORE_PROMPT_CATALOG = [
+	{
+		documentName: "behaviour.md",
+		label: "Response behavior",
+		description:
+			"Guidelines for escalation behavior and mode-aware response constraints.",
+		presets: [],
+	},
+	{
+		documentName: "participation.md",
+		label: "Participation policy",
+		description:
+			"Rules for when the AI should reply versus stay silent in mixed human/AI conversations.",
+		presets: [],
+	},
+	{
+		documentName: "grounding.md",
+		label: "Grounding policy",
+		description:
+			"Rules that require retrieval-first behavior for factual/product/policy responses.",
+		presets: [],
+	},
+	{
+		documentName: "capabilities.md",
+		label: "Capabilities policy",
+		description:
+			"Defines what actions/tools the AI is allowed or disallowed to perform.",
+		presets: [],
+	},
+	{
+		documentName: "visitor-contact.md",
+		label: "How and when to get visitor's contact details",
+		description:
+			"Define when and how the agent asks for visitor identity details (name/email).",
+		presets: VISITOR_CONTACT_PRESETS,
+	},
+	{
+		documentName: "decision.md",
+		label:
+			"How the agent should decide when to respond or not in a conversation",
+		description:
+			"Control the decision gate policy that determines when the AI should respond, observe, or assist the team.",
+		presets: SMART_DECISION_PRESETS,
+	},
+] as const satisfies readonly CorePromptStudioDefinition[];
+
 const BEHAVIOR_PROMPT_CATALOG_BY_ID = new Map(
 	BEHAVIOR_PROMPT_CATALOG.map((behavior) => [behavior.id, behavior])
 );
@@ -106,6 +160,10 @@ const BEHAVIOR_PROMPT_CATALOG_BY_DOCUMENT_NAME = new Map(
 	BEHAVIOR_PROMPT_CATALOG.map((behavior) => [behavior.documentName, behavior])
 );
 
+const EDITABLE_CORE_PROMPT_CATALOG_BY_DOCUMENT_NAME = new Map(
+	EDITABLE_CORE_PROMPT_CATALOG.map((entry) => [entry.documentName, entry])
+);
+
 export const EDITABLE_BEHAVIOR_CORE_DOCUMENT_NAMES = [
 	...new Set(BEHAVIOR_PROMPT_CATALOG.map((behavior) => behavior.documentName)),
 ] as const;
@@ -114,6 +172,10 @@ export function getBehaviorPromptCatalog(): readonly BehaviorPromptDefinition[]
 	return BEHAVIOR_PROMPT_CATALOG;
 }
 
+export function getEditableCorePromptCatalog(): readonly CorePromptStudioDefinition[] {
+	return EDITABLE_CORE_PROMPT_CATALOG;
+}
+
 export function getBehaviorPromptDefinition(
 	behaviorId: AiAgentBehaviorPromptId
 ): BehaviorPromptDefinition | null {
@@ -125,3 +187,11 @@ export function getBehaviorPromptDefinitionByDocumentName(
 ): BehaviorPromptDefinition | null {
 	return BEHAVIOR_PROMPT_CATALOG_BY_DOCUMENT_NAME.get(documentName) ?? null;
 }
+
+export function getEditableCorePromptDefinitionByDocumentName(
+	documentName: AiAgentEditableCorePromptDocumentName
+): CorePromptStudioDefinition | null {
+	return (
+		EDITABLE_CORE_PROMPT_CATALOG_BY_DOCUMENT_NAME.get(documentName) ?? null
+	);
+}

apps/api/src/ai-agent/prompts/documents.test.ts

@@ -9,9 +9,17 @@ import {
 
 describe("prompt document rules", () => {
 	it("accepts reserved core document names", () => {
+		expect(isCorePromptDocumentName("behaviour.md")).toBe(true);
+		expect(isCorePromptDocumentName("participation.md")).toBe(true);
+		expect(isCorePromptDocumentName("grounding.md")).toBe(true);
 		expect(isCorePromptDocumentName("capabilities.md")).toBe(true);
 		expect(isCorePromptDocumentName("decision.md")).toBe(true);
 		expect(isCorePromptDocumentName("visitor-contact.md")).toBe(true);
+		expect(() => assertCorePromptDocumentName("behaviour.md")).not.toThrow();
+		expect(() =>
+			assertCorePromptDocumentName("participation.md")
+		).not.toThrow();
+		expect(() => assertCorePromptDocumentName("grounding.md")).not.toThrow();
 		expect(() => assertCorePromptDocumentName("capabilities.md")).not.toThrow();
 		expect(() => assertCorePromptDocumentName("decision.md")).not.toThrow();
 		expect(() =>

apps/api/src/ai-agent/prompts/documents.ts

@@ -18,15 +18,28 @@ export const RESERVED_CORE_PROMPT_DOCUMENT_NAMES = new Set<string>(
 	CORE_PROMPT_DOCUMENT_NAMES
 );
 
-export const EDITABLE_BEHAVIOR_CORE_PROMPT_DOCUMENT_NAMES = [
+export const EDITABLE_CORE_PROMPT_DOCUMENT_NAMES = [
+	"behaviour.md",
+	"participation.md",
+	"grounding.md",
+	"capabilities.md",
 	"visitor-contact.md",
 	"decision.md",
 ] as const;
 
-export const EDITABLE_BEHAVIOR_CORE_PROMPT_DOCUMENT_NAME_SET = new Set<string>(
-	EDITABLE_BEHAVIOR_CORE_PROMPT_DOCUMENT_NAMES
+export const EDITABLE_CORE_PROMPT_DOCUMENT_NAME_SET = new Set<string>(
+	EDITABLE_CORE_PROMPT_DOCUMENT_NAMES
 );
 
+/**
+ * Backward-compatible aliases kept while behavior-specific studio endpoints
+ * remain available as wrappers around the generic core prompt studio.
+ */
+export const EDITABLE_BEHAVIOR_CORE_PROMPT_DOCUMENT_NAMES =
+	EDITABLE_CORE_PROMPT_DOCUMENT_NAMES;
+export const EDITABLE_BEHAVIOR_CORE_PROMPT_DOCUMENT_NAME_SET =
+	EDITABLE_CORE_PROMPT_DOCUMENT_NAME_SET;
+
 export const SKILL_PROMPT_NAME_REGEX = /^[a-z0-9][a-z0-9-]{1,62}\.md$/;
 
 export class PromptDocumentValidationError extends Error {

apps/api/src/ai-agent/prompts/instructions.ts

@@ -22,12 +22,6 @@ export function buildBehaviorInstructions(
 		instructions.push(escalationInstructions);
 	}
 
-	// Build capability list
-	const capabilities = buildCapabilitiesInstructions(settings);
-	if (capabilities) {
-		instructions.push(capabilities);
-	}
-
 	// Add mode-specific behavior
 	const modeInstructions = buildModeBehaviorInstructions(mode);
 	if (modeInstructions) {