JeanHuguesRobert

Public surface for generated Cogentia views. Tag browser (Gmail-style), not a folder tree. Default list order is recent first (sort=modified&dir=desc).

UX

Tags: OR within kind / repo / type; AND across dimensions (empty = any)
Example: type:md,type:json → markdown or JSON; add repo:cogentia → those types in cogentia only
Soft hierarchy: repo-kind.ext names; sort by name clusters by prefix
modified = file mtime on the store; produced = frontmatter generation date when present
Markdown links resolve to another published view or to GitHub; unresolved refs are plain text (no dead links)
JSON/YAML Pretty and Markdown HTML: auto-link well-formed URLs, owner/repo[/path], repo/path, ../repo, and repo-local paths like research/… / docs/… (→ GitHub in that repo). Markdown also linkifies bare file.md beside the source file. Bare repo names only in JSON/YAML (too noisy in prose). Raw stays plain; ?raw returns original bytes

Endpoints

Endpoint	Description
`GET /api/health`	Liveness
`GET /api/docs`	This contract as JSON
`GET /api/views`	List public views (same filters as HTML UI)
`GET /views/{filename}`	One view: HTML by default; ?raw; ?download
`GET /`	HTML tag browser (query: q, sort, dir, tag)
`GET /docs`	Human-readable documentation HTML

`GET /api/views` query

Param	Meaning
`tag`	comma-separated tag ids; OR within kind/repo/type, AND across (alias: tags)
`q`	search name/title/repo/kind/tags
`sort`	attention\|modified\|produced\|name\|kind\|ext\|type\|size (default: attention = importance then urgency)
`dir`	asc\|desc (default: desc)

Examples

Notable views

{
  "corpus-state.md": {
    "tag": "kind:corpus-state",
    "description": "Operational summary of local SQLite index cache + embeddings coverage + optional Supabase inventory. Metadata/counts only — no vectors or chunk bodies.",
    "machine_readable": "/views/corpus-state.json",
    "generator": "node scripts/cogentia.js corpus-state export",
    "publish": "node scripts/cogentia.js publish push corpus-state"
  },
  "continuations-list.md": {
    "tag": "kind:continuations",
    "description": "Alive continuations (default liveness=alive), analogous to open issues."
  },
  "current-issues-list.md": {
    "tag": "kind:issues",
    "description": "Open GitHub issues aggregate."
  }
}

View object (fields)

{
  "name": "basename",
  "title": "frontmatter title or name",
  "size": "bytes",
  "modified": "ISO mtime",
  "produced": "ISO content/generation date (frontmatter or mtime)",
  "ext": "md|json|txt|…",
  "repo": "string|null",
  "kind": "string",
  "tags": "[{type,id,label}]",
  "tag_ids": "string[]",
  "url": "/views/…",
  "cross_refs": {
    "view_id": "string",
    "view_url": "https://cogentia.fractavolta.com/views/…",
    "relation": "derived_mirror|operational_export|config_sample",
    "kind": "string",
    "repo": "string|null",
    "github": "{ full_name, path, url }|null",
    "site": "{ url, label }|null"
  },
  "visible": "boolean",
  "visibility_reason": "string"
}

Canonical docs in the corpus

cogentia/docs/views-store.md — keep the live contract and that file aligned when changing the API.

Base URL: https://cogentia.fractavolta.com