kennel 0.2.12 → 0.2.15

package/kernel/packages/schemas/SKILL.md

@@ -1,185 +0,0 @@
----
-name: kennel-schemas
-description: View, create, and update Kennel schema-backed collections (folder `schema.json` or `_schema.json` files with `x-kennel` hints) and their records — meetings, people, clients, projects, prospects, partners, research, or tasks. Use when the user asks to view, list, read, summarize, open, or link the custom items of a schema folder; or to give a folder a typed schema, frontmatter/YAML fields, icon and UI hints, filters, list or tab views, schema-backed Markdown records, or a reusable content pattern. Complements the kennel-cli skill (validation) and the raggle-schema-manager skill (raggle.json wiring).
----
-
-# Kennel Schemas
-
-This package (`@raggle-ai/schemas`) owns everything a custom schema promises:
-the `x-kennel` contract, schema loading, the record indexer, the server seam,
-and the viewer UI. This skill is the agent-facing guidance: how to view a
-collection's records and how to create or update the schema that defines them.
-
-The schema is the contract; records must follow it. The schema also becomes
-Raggle's display contract — as part of the same change, wire it into the
-relative `raggle.json` (see the raggle-schema-manager skill) or the collection
-stays invisible to search and views. For the collection/index behavior and
-`x-kennel` fields, see `docs/core-folders.md` in the Kennel repo.
-
-## Viewing a collection
-
-1. **Identify the collection folder.** Use the folder the user names, or the
-   folder containing the item they point at.
-2. **Find the owning schema.** Walk up from the folder for `schema.json`
-   (`_schema.json` when the folder already uses that convention;
-   `schema.json` wins when both exist) and search downward with
-   `find <folder> \( -name "schema.json" -o -name "_schema.json" \)`
-   (skip `node_modules`). Stop descending at nested schema folders — they own
-   their own items. A schema that is only a `$ref` points at a published
-   HTTPS schema; read the fetched target, and if the view later fails to
-   load, check that `$ref` first.
-3. **Read the schema for item anatomy.** Pull out `x-kennel.documents`
-   (which files are records and their parser), `title`, `properties`, and the
-   `x-kennel.ui` hints (`primaryField`, `secondaryField`, `filters`,
-   `numericFilters`, `sort`)
-   plus `x-kennel.icon`. State what one record is, how it is stored, and
-   which fields the viewer shows.
-4. **Enumerate the records.** For
-   `{ "glob": "*.md", "parser": "markdown-frontmatter" }` every Markdown file
-   with frontmatter is a record; for YAML globs every matching `.yml` file is
-   a record. Setup files (`AGENTS.md`, `README.md`, `SKILL.md`) are records
-   only when a pattern names them explicitly (folder records whose
-   frontmatter lives inside the file). Skip hidden folders and
-   `node_modules`.
-5. **Read each record's fields.** Parse frontmatter (Markdown) or the
-   YAML/JSON body. Title precedence: `title` field → first `# heading` →
-   filename. Badge candidates: `status`, `kind`, `type`, `relationship`,
-   then `date`, `updated`, `lastContact`. Detail candidates: `summary`,
-   `people`, `owner`, `nextAction`, `role`, `organisation`, `source`.
-6. **Present or open the records.** Render a list (title + badge + one-line
-   detail, grouped by folder when records span subfolders), and/or open the
-   collection in the viewer and return the link. Do not invent values;
-   unknown fields are "Not recorded".
-7. **Verify before reporting.** Run `kennel schema <folder>`,
-   `kennel doctor <folder>`, and `kennel validate <folder>` (the kennel-cli
-   skill; a separate compact-validator bundle). Report real discrepancies —
-   records missing declared fields, dangling file references — alongside the
-   view. When viewing through the viewer, confirm the collection page loads.
-
-## Viewing in the Kennel viewer
-
-| Target                                   | Command                                                        | What the user sees                              |
-| ---------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
-| Whole collection (folder)                | `knl view <folder>` (reuses 127.0.0.1:5180)                    | Folder viewer; the schema tab lists the records |
-| Single record file                       | `knl pop <record>.md` (reuses 127.0.0.1:5180)                  | One document pop-up                             |
-| Phone-accessible link (explicit request) | `kennel serve <folder> --lan` / `kennel pop <record>.md --lan` | Private LAN link (same network required)        |
-
-`kennel`, `kennel pop`, `kennel view`, and `kennel serve` above are the
-platform viewer CLI. The validation commands — `kennel schema`,
-`kennel doctor`, `kennel validate` — share the `kennel` name but come from
-the separate `kennel-cli` bundle; do not read one's output with the other's
-expectations. Localhost previews always reuse the single always-running hot
-viewer on `http://127.0.0.1:5180` — never add `--port` for localhost; for
-launch mechanics follow the kennel-preview skill.
-
-## Creating or updating a schema
-
-Workflow:
-
-1. Identify the exact folder that owns the collection.
-2. Read existing `schema.json`, `_schema.json`, `kennel.json`, `raggle.json`,
-   and nearby records before editing.
-3. Ask for missing product intent only when it cannot be inferred:
-   collection purpose, required record fields, icon or visual identity,
-   filters/groups/tabs and numeric ranges the UI must support, and the record
-   format (Markdown frontmatter, YAML, or JSON).
-4. For normal collections, ask whether to start from a published Raggle
-   schema. If the user gives a URL, fetch it and use it as the starting
-   point; otherwise use published schemas only as examples.
-5. Create or update the nearest `schema.json`. Use `_schema.json` only when
-   the folder already uses that convention.
-6. Update existing records, or create the smallest sample record, so the
-   folder validates against the schema.
-7. Run Kennel validation when available.
-8. **Wire it into the relative `raggle.json`** — the nearest one, walking up
-   from the collection folder. Add one `schemas` entry
-   `{ "path": "<collection folder>", "schema": "<schema file>" }`, both paths
-   relative to that `raggle.json`. Do not duplicate the entry in both the
-   repo root and a nested config. Without this entry the schema is dead
-   weight.
-
-Schema shape — JSON Schema draft 2020-12:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "meetings/schema.json",
-  "title": "Meetings",
-  "type": "object",
-  "x-kennel": {
-    "documents": [{ "glob": "*.md", "parser": "markdown-frontmatter" }],
-    "icon": "calendar-days",
-    "ui": {
-      "primaryField": "title",
-      "secondaryField": "date",
-      "filters": ["status", "type"],
-      "sort": [{ "field": "date", "direction": "desc" }]
-    }
-  },
-  "required": ["title", "slug", "status"],
-  "properties": {
-    "title": { "type": "string", "minLength": 1 },
-    "slug": { "$ref": "#/$defs/slug" },
-    "status": { "type": "string" }
-  },
-  "additionalProperties": true,
-  "$defs": {
-    "slug": {
-      "type": "string",
-      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-    }
-  }
-}
-```
-
-Treat `x-kennel.documents` as required for content discovery; `x-kennel.icon`
-and `x-kennel.ui` are optional hints. Icon names use Lucide kebab case
-(matching the UI icon set). Standard setup files (`AGENTS.md`, `README.md`,
-`SKILL.md`) are ignored unless a document pattern names them, so a
-folder-record collection like `*/AGENTS.md` keeps its records.
-
-Field design:
-
-- Put fields used for filters, tabs, sorting, badges, and search in
-  frontmatter or YAML.
-- Use enums for stable statuses, types, and stages; arrays for tags,
-  participants, evidence, next actions.
-- Use file-reference fields when the record points at other records
-  (`people/*.md`, `meetings/*.md`).
-- Use `format: "date"`, `format: "date-time"`, `format: "uri"`, and
-  `format: "email"` where useful.
-- Keep `additionalProperties: true` when existing records carry flexible
-  metadata.
-- Do not make a field required unless records can be filled consistently.
-
-Record setup — for Markdown records keep schema data in YAML frontmatter and
-prose in the body:
-
-```markdown
----
-title: Example Meeting
-slug: example-meeting
-status: planned
-date: 2026-08-10
-participants: []
----
-
-# Example Meeting
-```
-
-When creating examples, use known facts only: `null`, empty arrays, or clear
-placeholders where the schema allows them. Note the null caveat: a property
-typed `"number"` alone rejects an explicit `null`; pair `"type":
-["number", "null"]` on optional numeric fields.
-
-## Boundaries
-
-- Schema edits belong to this skill; record edits follow the repo's normal
-  content conventions. Re-view after either.
-- After importing or copying a published schema: adjust fields to the folder
-  purpose, keep required fields realistic, align icons and UI hints, remove
-  fields nobody will maintain, and validate current records against the
-  result.
-- If `kennel` is not available, verify the JSON parses and that required
-  fields match at least one record, and state that full validation did not
-  run.

package/kernel/packages/schemas/eslint.config.js

@@ -1,10 +0,0 @@
-import baseConfig from "@raggle-ai/eslint-config/base"
-import reactConfig from "@raggle-ai/eslint-config/react"
-
-export default [
-  ...baseConfig,
-  ...reactConfig,
-  {
-    ignores: ["dist/**", "**/_generated/", "vendor/**"],
-  },
-]

package/kernel/packages/schemas/package.json

@@ -1,81 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/package.json",
-  "name": "@raggle-ai/schemas",
-  "version": "0.1.0",
-  "description": "Schema-backed collection contracts, indexing, server seams, and UI for Kennel.",
-  "type": "module",
-  "license": "MIT",
-  "prettier": "@raggle-ai/prettier-config",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/raggle-ai/kennel.git",
-    "directory": "packages/schemas"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "files": [
-    "SKILL.md",
-    "src"
-  ],
-  "exports": {
-    ".": "./src/index.ts",
-    "./client": "./src/client.tsx",
-    "./manifest": "./src/manifest.ts",
-    "./node": "./src/node.ts",
-    "./server": "./src/server.ts",
-    "./contract": "./src/data/contract.ts",
-    "./favicon": "./src/data/favicon.ts",
-    "./config-file": "./src/data/config-file.ts",
-    "./workspace": "./src/data/workspace.ts"
-  },
-  "scripts": {
-    "test": "bun test test/*.test.mjs",
-    "typecheck": "tsc --noEmit",
-    "format": "prettier . --check --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
-    "format:fix": "prettier . --write --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
-    "lint": "eslint . --cache --cache-location .cache/.eslintcache",
-    "lint:fix": "eslint . --fix --cache --cache-location .cache/.eslintcache",
-    "clean": "git clean -xdf dist node_modules .cache .turbo/cache",
-    "pack:check": "npm pack --dry-run",
-    "publish:public:dry-run": "npm --@raggle-ai:registry=https://registry.npmjs.org publish --dry-run --access public --registry=https://registry.npmjs.org"
-  },
-  "dependencies": {
-    "@raggle-ai/ui": "workspace:*",
-    "@tanstack/react-query": "catalog:tanstack",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "lucide-react": "^0.562.0",
-    "picomatch": "^4.0.3",
-    "sharp": "^0.35.5",
-    "yaml": "^2.9.0",
-    "zod": "catalog:"
-  },
-  "peerDependencies": {
-    "react": ">=18.3.0"
-  },
-  "devDependencies": {
-    "@eslint/compat": "catalog:eslint",
-    "@eslint/eslintrc": "catalog:eslint",
-    "@ianvs/prettier-plugin-sort-imports": "catalog:prettier",
-    "@prettier/plugin-oxc": "catalog:prettier",
-    "@raggle-ai/eslint-config": "workspace:*",
-    "@raggle-ai/prettier-config": "workspace:*",
-    "@raggle-ai/tsconfig": "workspace:*",
-    "@types/node": "catalog:",
-    "@types/picomatch": "^4.0.2",
-    "@types/react": "catalog:react19",
-    "@types/react-dom": "catalog:react19",
-    "eslint": "catalog:eslint",
-    "eslint-plugin-unused-imports": "catalog:eslint",
-    "prettier": "catalog:prettier",
-    "prettier-plugin-classnames": "catalog:prettier",
-    "prettier-plugin-merge": "catalog:prettier",
-    "prettier-plugin-tailwindcss": "catalog:prettier",
-    "react": "catalog:react19",
-    "react-dom": "catalog:react19",
-    "typescript": "catalog:",
-    "typescript-eslint": "catalog:eslint"
-  }
-}

package/kernel/packages/schemas/src/client.tsx

@@ -1,137 +0,0 @@
-import { useEffect, useState } from "react"
-import { useQuery, useQueryClient } from "@tanstack/react-query"
-
-import { folderBarActions } from "@raggle-ai/ui/components/app-options"
-import { AppViewHeader } from "@raggle-ai/ui/components/app-view-header"
-
-import type { CoreCollection } from "./data/contract.ts"
-import type { CollectionSort } from "./data/params.ts"
-// import { collectionSortHref } from "./data/params.ts"
-import { readCollectionSort } from "./data/params.ts"
-import { CollectionView } from "./pages/collection.tsx"
-
-export type CollectionApiEvent =
-  "kennel:metadata-changed" | "kennel:workspace-changed"
-
-export type CollectionMetadataResponse = {
-  collection: CoreCollection
-  folder: string
-}
-
-export type CollectionRoute = {
-  collectionId?: string
-  folder?: string
-}
-
-export type CollectionHostProps = {
-  collectionHref: (folder: string, id: string) => string
-  documentHref: (folder: string, path: string) => string
-  folderHref: (folder: string) => string
-  homeHref: (folder: string) => string
-  href: string
-  openFolder?: (folder: string) => void
-  parseRoute: (href: string) => CollectionRoute
-  request: (
-    href: string,
-    part: "collections",
-    options: { id: string; signal?: AbortSignal; sort?: CollectionSort },
-  ) => Promise<CollectionMetadataResponse>
-  subscribeApiEvent: (
-    event: CollectionApiEvent,
-    handler: () => void,
-  ) => () => void
-}
-
-export function CollectionPage({
-  collectionHref,
-  documentHref,
-  folderHref,
-  homeHref,
-  href,
-  openFolder,
-  parseRoute,
-  request,
-  subscribeApiEvent,
-}: CollectionHostProps) {
-  const { folder, collectionId } = parseRoute(href)
-  const client = useQueryClient()
-  const hrefSort = readCollectionSort(href)
-  const [sort, setSort] = useState(hrefSort)
-  useEffect(() => {
-    setSort(hrefSort)
-  }, [hrefSort])
-  const applySort = (next: CollectionSort) => {
-    setSort(next)
-    // URL writes are disabled until saved views use them.
-    // if (typeof window !== "undefined")
-    //   window.history.replaceState(
-    //     null,
-    //     "",
-    //     collectionSortHref(window.location.href, next),
-    //   )
-  }
-  useEffect(() => {
-    const refresh = () =>
-      void client.invalidateQueries({ queryKey: ["collection", folder] })
-    const unsubscribeMetadata = subscribeApiEvent(
-      "kennel:metadata-changed",
-      refresh,
-    )
-    const unsubscribeWorkspace = subscribeApiEvent(
-      "kennel:workspace-changed",
-      refresh,
-    )
-    return () => {
-      unsubscribeMetadata()
-      unsubscribeWorkspace()
-    }
-  }, [client, folder, subscribeApiEvent])
-
-  const query = useQuery<CollectionMetadataResponse>({
-    queryKey: ["collection", folder, collectionId, sort],
-    enabled: Boolean(folder && collectionId),
-    // Keep the controls and their filter state mounted during an order change.
-    // Never show records from a different folder or collection.
-    placeholderData: (previous, previousQuery) =>
-      previousQuery &&
-      previousQuery.queryKey[1] === folder &&
-      previousQuery.queryKey[2] === collectionId
-        ? previous
-        : undefined,
-    queryFn: ({ signal }) =>
-      request(href, "collections", { id: collectionId!, signal, sort }),
-  })
-
-  if (query.error)
-    return <p role="alert">Could not load collection: {query.error.message}</p>
-  if (!query.data) return <p role="status">Loading collection…</p>
-
-  return (
-    <>
-      <AppViewHeader
-        actions={folderBarActions({
-          folderPath: query.data.folder,
-          onOpenFolder: openFolder
-            ? () => openFolder(query.data.folder)
-            : undefined,
-        })}
-        className="collection-page-header"
-        collectionHref={(id) => collectionHref(query.data.folder, id)}
-        folder={query.data.folder}
-        folderHref={folderHref}
-        homeHref={homeHref(query.data.folder)}
-      />
-      <CollectionView
-        href={href}
-        key={`${folder}:${collectionId}`}
-        folder={query.data.folder}
-        collection={query.data.collection}
-        documentHref={(path) => documentHref(query.data.folder, path)}
-        folderHref={folderHref}
-        onSort={applySort}
-        refreshing={query.isFetching}
-        sort={sort}
-      />
-    </>
-  )
-}

package/kernel/packages/schemas/src/data/config-file.ts

@@ -1,37 +0,0 @@
-import { existsSync, readFileSync } from "node:fs"
-import { join } from "node:path"
-
-// Configuration lookup is shared by every Kennel renderer.
-
-export const indexConfigFilenames = ["raggle.json", "docs.config.json"]
-
-export function resolveIndexConfigPath(
-  root = process.cwd(),
-  filenames = indexConfigFilenames,
-) {
-  for (const filename of filenames) {
-    const candidate = join(root, filename)
-
-    if (existsSync(candidate)) return candidate
-  }
-
-  return undefined
-}
-
-export function readIndexDocsConfig(
-  root = process.cwd(),
-  options: { filenames?: string[] } = {},
-) {
-  const configPath = resolveIndexConfigPath(
-    root,
-    options.filenames ?? indexConfigFilenames,
-  )
-
-  if (!configPath) {
-    throw new Error(
-      `No index config found in ${root}. Expected one of: ${indexConfigFilenames.join(", ")}`,
-    )
-  }
-
-  return JSON.parse(readFileSync(configPath, "utf8"))
-}

package/kernel/packages/schemas/src/data/contract.ts

@@ -1,174 +0,0 @@
-import { z } from "zod"
-
-export type IndexIssue = { path: string; message: string }
-
-export type KennelDocumentConfig = Record<string, unknown> & {
-  glob?: unknown
-  parser?: unknown
-  path?: unknown
-}
-
-export type KennelCollectionSort = {
-  field: string
-  direction: "asc" | "desc"
-}
-
-export type KennelCollectionUi = {
-  primaryField: string
-  secondaryField?: string
-  filters: string[] | "all"
-  numericFilters?: string[]
-  sort?: KennelCollectionSort[]
-  navLabel?: string
-}
-
-export type KennelSchemaConfig = {
-  title?: string
-  icon?: string
-  documents: KennelDocumentConfig[]
-  ui: KennelCollectionUi
-}
-
-export type CoreRecordIcon = {
-  readonly source: "local" | "favicon"
-  readonly host?: string
-  readonly path?: string
-}
-
-/** Inline icon asset attached to a collection response. `data` is base64. */
-export type KennelIconAsset = {
-  readonly data?: string
-  readonly mediaType: string
-  readonly source?: "local" | "favicon"
-  readonly url?: string
-}
-
-export type CoreRecord = {
-  id: string
-  path: string
-  relativePath: string
-  title: string
-  modifiedAt: number
-  fields: Record<string, unknown>
-  validationErrors: IndexIssue[]
-  /** Icon detected from frontmatter; resolved to an asset per request. */
-  icon?: CoreRecordIcon
-  iconAssetKey?: string
-}
-
-export type CoreCollection = {
-  id: string
-  folder: string
-  schemaPath: string
-  title: string
-  navLabel?: string
-  icon?: string
-  count: number
-  diagnostics: IndexIssue[]
-  revision: string
-  indexedAt: string
-  state: "ready" | "error"
-  ui: {
-    primaryField: string
-    secondaryField?: string
-    filters: string[]
-    numericFilters: string[]
-    sort?: KennelCollectionSort[]
-  }
-  /** Per-request record icon assets; records reference them by `iconAssetKey`. */
-  assets?: Record<string, KennelIconAsset>
-  records: CoreRecord[]
-}
-
-export type CoreCollectionSummary = Omit<CoreCollection, "records">
-export type CoreCollectionSummaryPayload = Omit<CoreCollectionSummary, "ui">
-
-export type CoreFolderIndex = {
-  list(
-    input: string,
-    options?: { boundary?: string },
-  ): Promise<{
-    folder: string
-    root: string
-    revision: string
-    state: "ready" | "error"
-    collections: CoreCollection[]
-    dependencies: string[]
-  }>
-  invalidate(changed: string): string[]
-  stats: { collectionsBuilt: number; recordsRead: number }
-}
-
-export const issueSchema = z.object({ path: z.string(), message: z.string() })
-
-export const coreRecordIconSchema = z.object({
-  source: z.enum(["local", "favicon"]),
-  host: z.string().optional(),
-  path: z.string().optional(),
-})
-
-export const kennelIconAssetSchema = z.object({
-  data: z.string().optional(),
-  mediaType: z.string(),
-  source: z.enum(["local", "favicon"]).optional(),
-  url: z.string().optional(),
-})
-
-export const coreCollectionSortSchema = z.object({
-  field: z.string(),
-  direction: z.enum(["asc", "desc"]),
-})
-
-export const coreCollectionUiSchema = z.object({
-  primaryField: z.string(),
-  secondaryField: z.string().optional(),
-  filters: z.array(z.string()),
-  numericFilters: z.array(z.string()),
-  sort: z.array(coreCollectionSortSchema).optional(),
-})
-
-export const collectionSummarySchema = z.object({
-  id: z.string().optional(),
-  count: z.number().optional(),
-  navLabel: z.string().optional(),
-  icon: z.string().optional(),
-  revision: z.string().optional(),
-  indexedAt: z.string().optional(),
-  state: z.enum(["ready", "error"]).optional(),
-  diagnostics: z.array(issueSchema).optional(),
-  folder: z.string(),
-  schemaPath: z.string(),
-  title: z.string(),
-})
-
-export const coreRecordSchema = z.object({
-  icon: coreRecordIconSchema.optional(),
-  iconAssetKey: z.string().optional(),
-  id: z.string(),
-  path: z.string(),
-  relativePath: z.string(),
-  title: z.string(),
-  modifiedAt: z.number(),
-  fields: z.record(z.string(), z.unknown()),
-  validationErrors: z.array(issueSchema),
-})
-
-export const coreCollectionSchema = collectionSummarySchema.extend({
-  id: z.string(),
-  count: z.number(),
-  diagnostics: z.array(issueSchema),
-  revision: z.string(),
-  indexedAt: z.string(),
-  state: z.enum(["ready", "error"]),
-  ui: coreCollectionUiSchema,
-  assets: z.record(z.string(), kennelIconAssetSchema).optional(),
-  records: z.array(coreRecordSchema),
-})
-
-/** Omit record bodies from navigation payloads. */
-export function collectionSummary({
-  records: _records,
-  ...summary
-}: CoreCollection): CoreCollectionSummary {
-  return summary
-}