init: specs for agents

AGENTS.md

@@ -1,31 +1,4 @@
-## Project Configuration
-
-- **Language**: TypeScript
-- **Package Manager**: npm
-- **Add-ons**: prettier, eslint, tailwindcss, vitest, playwright, mcp
-
----
-
-You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively:
-
-## Available MCP Tools:
-
-### 1. list-sections
-
-Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths.
-When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.
-
-### 2. get-documentation
-
-Retrieves full documentation content for specific sections. Accepts single or multiple sections.
-After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task.
-
-### 3. svelte-autofixer
-
-Analyzes Svelte code and returns issues and suggestions.
-You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.
-
-### 4. playground-link
-
-Generates a Svelte Playground link with the provided code.
-After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.
+@specs/ARCHITECTURE.md
+@specs/DESIGN.md
+@specs/CODING_CONVENTION.md
+@specs/MCP_TOOLS.md

specs/ARCHITECTURE.md

@@ -0,0 +1,119 @@
+# Architecture
+
+## Overview
+
+loco-web-admin is a SvelteKit web application for managing the infrastructure of AI agents. Users manage agents and their dependencies (models, tools, skills, knowledge bases, memory, ...) through the web UI. The backend persists all resources as Kubernetes Custom Resources (CRs) via a GitOps repository, reads live runtime status directly from the K8s API server. A separate K8s operator (out of scope) reconciles the infrastructure.
+
+loco-web-admin is mainly used for observability for all users and management for advanced users. To manage resources, using AI agents in the GitOps repository is recommended over using this web UI directly. The GitOps repository is the SSoT and all changes will be reflected on the UI for further inspections and modifications.
+
+loco-web-admin can be deployed locally for local development or as a PaaS with multi-tenancy.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                        Browser                           │
+│   ┌──────────────────────────────────────────────────┐   │
+│   │              SvelteKit Frontend                  │   │
+│   └─────────────────────┬────────────────────────────┘   │
+└─────────────────────────┼────────────────────────────────┘
+                          │ HTTP
+┌─────────────────────────▼────────────────────────────────┐
+│                  SvelteKit Backend                       │
+│       (auth, multi-tenancy, resource management, ...)    │
+└──────┬─────────────────────────────────┬─────────────────┘
+       │ Git API                         │ K8s API
+       │ (CRUD via CRs + PRs)            │ (live status)
+┌──────▼──────┐                   ┌──────▼──────┐
+│  Git Repo   │                   │ K8s API     │
+│  (GitOps)   │                   │ Server      │
+└─────────────┘                   └──────┬──────┘
+                                         │
+                                  ┌──────▼───────┐
+                                  │ K8s Operator │ ← out of scope
+                                  │              │
+                                  └──────────────┘
+```
+
+## Domain Model
+
+Core entities:
+
+- **Stack**, a collection of all essential components required for running agents (such as gateway, database, vector store, ...) that are shared among agents and other components
+- **Model**, a self-hosted or a third-party API for model inference, including language models, embedding models, and reranker models
+- **Tool**, a self-hosted or a third-party MCP server
+- **Knowledge Base**, a self-hosted or third-party API for retrieval (and RAG pipeline)
+- **Skill**, a bundle of definitions for a reusable agent skill
+- **Memory**, a self-hosted database for short-term agent memory
+- **Agent**, a self-hosted instance of an AI agent
+
+| Primitive          | Answers                                                     |
+| ------------------ | ----------------------------------------------------------- |
+| **Model**          | How does the agent reason/generate?                         |
+| **Tool**           | How does the agent act on external systems?                 |
+| **Knowledge Base** | What external/static information can it retrieve?           |
+| **Skill**          | How does the agent perform a reusable capability?           |
+| **Memory**         | What has it learned or experienced?                         |
+| **Agent**          | What autonomous reasoning loop composes these capabilities? |
+
+## GitOps Flow
+
+1. User creates/edits an agent (or other resource) in the UI
+2. On "Save", the backend renders a K8s CR YAML containing the full spec
+3. Backend commits the CR file in the configured Git repository
+4. Backend calls the K8s API server to create/patch the resource
+5. The K8s operator (out of scope) picks up the CR and reconciles the components
+
+## Route Structure
+
+```
+/api/workspaces                                                  → workspaces available to the user
+/api/workspaces/[workspaceId]/[resource=resource]                → list/create resource entities
+/api/workspaces/[workspaceId]/[resource=resource]/[id]           → get/update/delete resource entities
+/api/workspaces/[workspaceId]/[resource=resource]/[id]/status    → live status from K8s resources
+/api/workspaces/[workspaceId]/[resource=resource]/[id]/changes   → Git history and change context
+/api/workspaces/[workspaceId]/[resource=resource]/[id]/resources → child K8s resources (deployments/pods/services)
+
+/workloads/models                       → model management
+/workloads/tools                        → tool management
+/workloads/kbs                          → knowledge base management
+/workloads/skills                       → skill management
+/workloads/memories                     → memory management
+/workloads/agents                       → agent management
+
+/auth/login                                                   → credential-based sign-in page
+/auth/logout                                                  → session clear + redirect
+```
+
+## Frontend Stack
+
+| Layer      | Technology               |
+| ---------- | ------------------------ |
+| Framework  | SvelteKit 5 (Runes mode) |
+| Language   | TypeScript (strict)      |
+| Styling    | Tailwind CSS v4          |
+| Unit tests | Vitest (browser + node)  |
+| E2E tests  | Playwright               |
+| Linting    | ESLint + Prettier        |
+
+## Key Modules
+
+### `src/lib/server/`
+
+Server modules for initialization, auth, workspace management, Git-backed catalog, and K8s resource access.
+
+### `src/routes/api/workspaces/`
+
+SvelteKit endpoint handlers that bridge HTTP requests to workspace-scoped catalog/resources operations.
+
+### `src/lib/components/`
+
+Reusable UI components shared across routes (forms, selectors, tables, badges).
+
+## Multi-tenancy
+
+Resources are isolated into workspaces. User has access to one or more workspaces.
+
+Only one workspace will be active in local mode.
+
+## Authentication
+
+File-based credential auth (JWT cookie) is enabled when auth env vars are configured; otherwise auth is bypassed with a local default admin user.

specs/CODING_CONVENTION.md

@@ -0,0 +1,69 @@
+# Coding Conventions
+
+## Stack
+
+- **Language**: TypeScript (strict mode)
+- **Framework**: SvelteKit 5 (Runes mode)
+- **Package Manager**: npm
+- **Styling**: Tailwind CSS v4
+- **Testing**: Vitest (unit/component), Playwright (e2e)
+- **Linting**: ESLint + Prettier
+
+## Formatting
+
+- Tabs for indentation, single quotes, trailing commas, semicolons
+- Print width: 100 characters
+- Import order: node built-ins → third-party → `$app/*` → `$lib/*` → relative
+- **Always use absolute imports** — prefer `$lib/...` and `$app/...` over relative paths. The only allowed relative imports are SvelteKit auto-generated route types (`./$types`), which cannot be referenced absolutely
+- **Always run Prettier and ESLint** (`npm run format && npx eslint --fix`) before finalizing any code change — never hand-format
+
+## Svelte
+
+- Always use Svelte 5 Runes (`$state`, `$derived`, `$effect`) — no legacy Options API
+- Store reactive state in `*.svelte.ts` files under `src/lib/stores/`
+- Run `svelte-autofixer` (via MCP) on all new Svelte code before finalizing
+- Components should be exported through `index.ts` under `$lib/components/{ComponentName}`
+
+## TypeScript
+
+- No `any` — use `unknown` and narrow explicitly
+- Prefer `type` over `interface` for data shapes; use `interface` for extension points
+- Co-locate types with the module that owns them
+- **Prefer arrow functions over `function` declarations when assigning to a variable** — `function` declarations are fine for class methods; use arrows everywhere else:
+
+  ```ts
+  // ✗ function expression as variable
+  const handler = function (x: number) {
+  	return x * 2;
+  };
+
+  // ✓ arrow function
+  const handler = (x: number) => x * 2;
+
+  // ✗ top-level named function (not a variable)
+  function helper(x: number) {
+  	return x * 2;
+  }
+
+  // ✓ class method (not a variable)
+  class Foo {
+  	bar() {
+  		return 1;
+  	}
+  }
+  ```
+
+- **Exports go at the bottom of the file** — never use inline `export` on a declaration. Collect all public symbols in a single `export` / `export type` statement at the end:
+
+  ```ts
+  // ✗ inline export
+  export type Foo = { ... };
+  export const bar = () => { ... }
+
+  // ✓ bottom export
+  type Foo = { ... };
+  const bar = () => { ... }
+
+  export type { Foo };
+  export { bar };
+  ```

specs/DESIGN.md

@@ -0,0 +1,176 @@
+# Design
+
+## Domain Models
+
+The UI maintains a stable set of domain models — its canonical, backend-agnostic representation of each resource, used by all forms and stores. They are an intermediate representation: they translate to and from the Custom Resources of whichever backend the deployment targets — the platform's own operator, or a community standard such as kagent or KServe. Field-level detail is defined in the individual entity design specs.
+
+### External vs Managed
+
+Every major resource type exists in two variants that the UI must handle:
+
+- **External**: third-party or externally hosted (e.g. the OpenAI API, a SaaS MCP server). The requests will be proxied via a Gateway. The user provides an endpoint URL and credentials.
+- **Managed**: deployed in-cluster by the operator (e.g. a self-hosted llama.cpp model, a custom MCP server). The user provides a container image reference and configuration; the operator manages the Deployment.
+
+The UI unifies each pair into a single entity concept with a variant discriminator. Form fields and validation rules differ by variant.
+
+### Core Entities
+
+- **Model** — an LLM provider configuration (language, embedding, or reranker). Holds provider identity, endpoint, credentials, and inference defaults.
+- **Tool** — an MCP server endpoint. Holds the URL, transport type, and authentication method.
+- **Knowledge Base** — a RAG data source. Holds chunking strategy, embedding model reference, and indexed document configuration.
+- **Skill** - a collection of prompts and configurations for a reusable skill that will be mounted onto agents.
+- **Memory** - a service for storing and retrieving shared transient/short-term memories.
+- **Agent** — the primary deployable unit. References a model, a set of tools, a set of skills, a set of memories, and a set of knowledge bases.
+
+### Supporting Entities
+
+- **Stack** - Shared components such as gateway and databases.
+- **Secret** - API keys for third-party authentications.
+
+---
+
+## Core User Flows
+
+Two major paths are supported:
+
+### Manual
+
+- Search for a component (model, tool, knowledge base, skill, memory, agent, ...)
+- Create, read, update, or delete a component
+- Inspect the live status of a deployed component
+- Test a component
+- Check and manage the cost generated by a component
+
+### AI-Assisted
+
+- All manual operations, but initiated and driven through the embedded AI chatbot
+- Ask questions about the platform, configuration options, and the UI itself
+
+---
+
+## Multi-tenancy
+
+The platform is designed for shared use across multiple teams. Each team operates within a **workspace** — an isolated namespace that owns its own models, tools, knowledge bases, skills, memories, and agents. Workspace membership and permissions are managed through the workspace settings.
+
+---
+
+## Information Architecture
+
+### Sitemap
+
+```
+Home
+├── Playground
+│   ├── Session list
+│   └── [Session]                       → Active chat session with a selected agent
+├── Usage
+│   ├── Cost dashboard
+│   └── Cost settings
+├── Utilities
+│   ├── Agent test
+│   ├── Knowledge base test
+│   ├── Tool (MCP) test
+│   └── Model test
+├── Workloads
+│   ├── Agents
+│   │   ├── Agent list
+│   │   ├── New agent
+│   │   └── [Agent]
+│   │       ├── Detail & status
+│   │       └── Edit
+│   ├── Memories
+│   │   ├── Memory list
+│   │   ├── New memory
+│   │   └── [Memory]
+│   │       ├── Detail & status
+│   │       └── Edit
+│   ├── Skills
+│   │   ├── Skill list
+│   │   ├── New skill
+│   │   └── [Skill]
+│   │       ├── Detail & definitions
+│   │       └── Edit
+│   ├── Knowledge Bases
+│   │   ├── Knowledge base list
+│   │   ├── New knowledge base
+│   │   └── [Knowledge Base]
+│   │       ├── Detail & documents & status
+│   │       └── Edit
+│   ├── Tools
+│   │   ├── Tool list
+│   │   ├── New tool
+│   │   └── [Tool]
+│   │       ├── Detail & status
+│   │       └── Edit
+│   ├── Models
+│   │   ├── Model list
+│   │   ├── New model
+│   │   └── [Model]
+│   │       ├── Detail & status
+│   │       └── Edit
+│   └── Stacks
+│       ├── Stack list
+│       ├── New Stack
+│       └── [Stack]
+│           ├── Detail & status
+│           └── Edit
+├── Workspace settings
+└── User settings
+```
+
+### Application Shell
+
+The shell is a three-column layout:
+
+```
+┌──────────┬─────────────────────────────────┬───────────┐
+│          │  Top bar                        │           │
+│          ├─────────────────────────────────┤           │
+│ Sidebar  │                                 │ Assistant │
+│          │  Main content                   │  panel    │
+│          │                                 │           │
+│          │                                 │           │
+└──────────┴─────────────────────────────────┴───────────┘
+```
+
+- **Sidebar** (left): primary navigation — workspace switcher, section links, user menu. Collapsible to an icon rail to maximise content width.
+- **Main content** (center): page content with a top bar carrying the page title, breadcrumbs, and contextual actions.
+- **AI assistant panel** (right): persistent but collapsed by default; expands as a fixed-width drawer.
+
+---
+
+## UI Principles
+
+- **Clarity over decoration**: no gratuitous animations or chrome. Every element earns its space.
+- **Inline editing**: prefer editing in-place over separate edit pages where feasible.
+- **Immediate feedback**: loading states, optimistic updates, clear error messages.
+- **CR transparency**: users can always see the YAML their config will produce.
+- **Desktop-first**: primary use case is a developer at a workstation.
+
+---
+
+## Visual Design
+
+### Component Library
+
+**shadcn-svelte** is the component library. Components are installed into `$lib/components/controls/` via the shadcn-svelte CLI and customized in place. Do not wrap shadcn components in extra abstraction layers — edit them directly when customization is needed.
+
+shadcn-svelte uses **bits-ui** for headless primitives and is fully compatible with Svelte 5 Runes.
+
+### Aesthetic
+
+Dark theme with a **Glassmorphism** aesthetic: frosted-glass panels floating over a gradient mesh background. Card, dialog, and popover surfaces use `backdrop-filter` blur with semi-transparent fills. The background is a deep navy with subtle radial gradient accents.
+
+### Color System
+
+- Accent / primary: oklch(0.496 0.265 301.924)
+- Glass surfaces: low-opacity fills with subtle white borders
+- Status colors: blue (open), green (healthy), slate (pending), red (error), amber (warning)
+
+### Elevation & Depth
+
+Three glass levels of increasing blur and opacity: background panels → cards/forms → dialogs/popovers.
+
+### Icons
+
+Lucide via `lucide-svelte`. Slightly muted at rest, full opacity on hover/active.

specs/MCP_TOOLS.md

@@ -0,0 +1,22 @@
+# MCP Tools
+
+The Svelte MCP server provides access to comprehensive Svelte 5 and SvelteKit documentation.
+
+## list-sections
+
+Use this **first** to discover all available documentation sections. Returns titles, use_cases, and paths.
+Always call this at the start of any Svelte/SvelteKit task to find relevant sections.
+
+## get-documentation
+
+Retrieves full documentation for specific sections. After `list-sections`, fetch **all** sections relevant to the task (use the `use_cases` field to judge relevance).
+
+## svelte-autofixer
+
+Analyzes Svelte code and returns issues and suggestions.
+**Must be called on all new Svelte code before sending it to the user.** Keep calling until no issues remain.
+
+## playground-link
+
+Generates a Svelte Playground link for the provided code.
+Only call after explicit user confirmation, and **never** when code has already been written to project files.