kenaz 0.0.0-stage → 0.3.2

package/core/.agents/skills/supabase-postgres-best-practices/references/schema-foreign-key-indexes.md

@@ -0,0 +1,59 @@
+---
+title: Index Foreign Key Columns
+impact: HIGH
+impactDescription: 10-100x faster JOINs and CASCADE operations
+tags: foreign-key, indexes, joins, schema
+---
+
+## Index Foreign Key Columns
+
+Postgres does not automatically index foreign key columns. Missing indexes cause slow JOINs and CASCADE operations.
+
+**Incorrect (unindexed foreign key):**
+
+```sql
+create table orders (
+  id bigint generated always as identity primary key,
+  customer_id bigint references customers(id) on delete cascade,
+  total numeric(10,2)
+);
+
+-- No index on customer_id!
+-- JOINs and ON DELETE CASCADE both require full table scan
+select * from orders where customer_id = 123;  -- Seq Scan
+delete from customers where id = 123;          -- Locks table, scans all orders
+```
+
+**Correct (indexed foreign key):**
+
+```sql
+create table orders (
+  id bigint generated always as identity primary key,
+  customer_id bigint references customers(id) on delete cascade,
+  total numeric(10,2)
+);
+
+-- Always index the FK column
+create index orders_customer_id_idx on orders (customer_id);
+
+-- Now JOINs and cascades are fast
+select * from orders where customer_id = 123;  -- Index Scan
+delete from customers where id = 123;          -- Uses index, fast cascade
+```
+
+Find missing FK indexes:
+
+```sql
+select
+  conrelid::regclass as table_name,
+  a.attname as fk_column
+from pg_constraint c
+join pg_attribute a on a.attrelid = c.conrelid and a.attnum = any(c.conkey)
+where c.contype = 'f'
+  and not exists (
+    select 1 from pg_index i
+    where i.indrelid = c.conrelid and a.attnum = any(i.indkey)
+  );
+```
+
+Reference: [Foreign Keys](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-FK)

package/core/.agents/skills/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md

@@ -0,0 +1,55 @@
+---
+title: Use Lowercase Identifiers for Compatibility
+impact: MEDIUM
+impactDescription: Avoid case-sensitivity bugs with tools, ORMs, and AI assistants
+tags: naming, identifiers, case-sensitivity, schema, conventions
+---
+
+## Use Lowercase Identifiers for Compatibility
+
+PostgreSQL folds unquoted identifiers to lowercase. Quoted mixed-case identifiers require quotes forever and cause issues with tools, ORMs, and AI assistants that may not recognize them.
+
+**Incorrect (mixed-case identifiers):**
+
+```sql
+-- Quoted identifiers preserve case but require quotes everywhere
+CREATE TABLE "Users" (
+  "userId" bigint PRIMARY KEY,
+  "firstName" text,
+  "lastName" text
+);
+
+-- Must always quote or queries fail
+SELECT "firstName" FROM "Users" WHERE "userId" = 1;
+
+-- This fails - Users becomes users without quotes
+SELECT firstName FROM Users;
+-- ERROR: relation "users" does not exist
+```
+
+**Correct (lowercase snake_case):**
+
+```sql
+-- Unquoted lowercase identifiers are portable and tool-friendly
+CREATE TABLE users (
+  user_id bigint PRIMARY KEY,
+  first_name text,
+  last_name text
+);
+
+-- Works without quotes, recognized by all tools
+SELECT first_name FROM users WHERE user_id = 1;
+```
+
+Common sources of mixed-case identifiers:
+
+```sql
+-- ORMs often generate quoted camelCase - configure them to use snake_case
+-- Migrations from other databases may preserve original casing
+-- Some GUI tools quote identifiers by default - disable this
+
+-- If stuck with mixed-case, create views as a compatibility layer
+CREATE VIEW users AS SELECT "userId" AS user_id, "firstName" AS first_name FROM "Users";
+```
+
+Reference: [Identifiers and Key Words](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)

package/core/.agents/skills/supabase-postgres-best-practices/references/schema-partitioning.md

@@ -0,0 +1,55 @@
+---
+title: Partition Large Tables for Better Performance
+impact: MEDIUM-HIGH
+impactDescription: 5-20x faster queries and maintenance on large tables
+tags: partitioning, large-tables, time-series, performance
+---
+
+## Partition Large Tables for Better Performance
+
+Partitioning splits a large table into smaller pieces, improving query performance and maintenance operations.
+
+**Incorrect (single large table):**
+
+```sql
+create table events (
+  id bigint generated always as identity,
+  created_at timestamptz,
+  data jsonb
+);
+
+-- 500M rows, queries scan everything
+select * from events where created_at > '2024-01-01';  -- Slow
+vacuum events;  -- Takes hours, locks table
+```
+
+**Correct (partitioned by time range):**
+
+```sql
+create table events (
+  id bigint generated always as identity,
+  created_at timestamptz not null,
+  data jsonb
+) partition by range (created_at);
+
+-- Create partitions for each month
+create table events_2024_01 partition of events
+  for values from ('2024-01-01') to ('2024-02-01');
+
+create table events_2024_02 partition of events
+  for values from ('2024-02-01') to ('2024-03-01');
+
+-- Queries only scan relevant partitions
+select * from events where created_at > '2024-01-15';  -- Only scans events_2024_01+
+
+-- Drop old data instantly
+drop table events_2023_01;  -- Instant vs DELETE taking hours
+```
+
+When to partition:
+
+- Tables > 100M rows
+- Time-series data with date-based queries
+- Need to efficiently drop old data
+
+Reference: [Table Partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html)

package/core/.agents/skills/supabase-postgres-best-practices/references/schema-primary-keys.md

@@ -0,0 +1,61 @@
+---
+title: Select Optimal Primary Key Strategy
+impact: HIGH
+impactDescription: Better index locality, reduced fragmentation
+tags: primary-key, identity, uuid, serial, schema
+---
+
+## Select Optimal Primary Key Strategy
+
+Primary key choice affects insert performance, index size, and replication
+efficiency.
+
+**Incorrect (problematic PK choices):**
+
+```sql
+-- identity is the SQL-standard approach
+create table users (
+  id serial primary key  -- Works, but IDENTITY is recommended
+);
+
+-- Random UUIDs (v4) cause index fragmentation
+create table orders (
+  id uuid default gen_random_uuid() primary key  -- UUIDv4 = random = scattered inserts
+);
+```
+
+**Correct (optimal PK strategies):**
+
+```sql
+-- Use IDENTITY for sequential IDs (SQL-standard, best for most cases)
+create table users (
+  id bigint generated always as identity primary key
+);
+
+-- For distributed systems needing UUIDs, use UUIDv7 (time-ordered)
+-- Requires pg_uuidv7 extension: create extension pg_uuidv7;
+create table orders (
+  id uuid default uuid_generate_v7() primary key  -- Time-ordered, no fragmentation
+);
+
+-- Alternative: time-prefixed IDs for sortable, distributed IDs (no extension needed)
+create table events (
+  id text default concat(
+    to_char(now() at time zone 'utc', 'YYYYMMDDHH24MISSMS'),
+    gen_random_uuid()::text
+  ) primary key
+);
+```
+
+Guidelines:
+
+- Single database: `bigint identity` (sequential, 8 bytes, SQL-standard)
+- Distributed/exposed IDs: UUIDv7 (requires pg_uuidv7) or ULID (time-ordered, no
+  fragmentation)
+- `serial` works but `identity` is SQL-standard and preferred for new
+  applications
+- Avoid random UUIDs (v4) as primary keys on large tables (causes index
+  fragmentation)
+
+Reference:
+[Identity Columns](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-PARMS-GENERATED-IDENTITY)

package/core/.agents/skills/supabase-postgres-best-practices/references/security-privileges.md

@@ -0,0 +1,54 @@
+---
+title: Apply Principle of Least Privilege
+impact: MEDIUM
+impactDescription: Reduced attack surface, better audit trail
+tags: privileges, security, roles, permissions
+---
+
+## Apply Principle of Least Privilege
+
+Grant only the minimum permissions required. Never use superuser for application queries.
+
+**Incorrect (overly broad permissions):**
+
+```sql
+-- Application uses superuser connection
+-- Or grants ALL to application role
+grant all privileges on all tables in schema public to app_user;
+grant all privileges on all sequences in schema public to app_user;
+
+-- Any SQL injection becomes catastrophic
+-- drop table users; cascades to everything
+```
+
+**Correct (minimal, specific grants):**
+
+```sql
+-- Create role with no default privileges
+create role app_readonly nologin;
+
+-- Grant only SELECT on specific tables
+grant usage on schema public to app_readonly;
+grant select on public.products, public.categories to app_readonly;
+
+-- Create role for writes with limited scope
+create role app_writer nologin;
+grant usage on schema public to app_writer;
+grant select, insert, update on public.orders to app_writer;
+grant usage on sequence orders_id_seq to app_writer;
+-- No DELETE permission
+
+-- Login role inherits from these
+create role app_user login password 'xxx';
+grant app_writer to app_user;
+```
+
+Revoke public defaults:
+
+```sql
+-- Revoke default public access
+revoke all on schema public from public;
+revoke all on all tables in schema public from public;
+```
+
+Reference: [Roles and Privileges](https://supabase.com/blog/postgres-roles-and-privileges)

package/core/.agents/skills/supabase-postgres-best-practices/references/security-rls-basics.md

@@ -0,0 +1,50 @@
+---
+title: Enable Row Level Security for Multi-Tenant Data
+impact: CRITICAL
+impactDescription: Database-enforced tenant isolation, prevent data leaks
+tags: rls, row-level-security, multi-tenant, security
+---
+
+## Enable Row Level Security for Multi-Tenant Data
+
+Row Level Security (RLS) enforces data access at the database level, ensuring users only see their own data.
+
+**Incorrect (application-level filtering only):**
+
+```sql
+-- Relying only on application to filter
+select * from orders where user_id = $current_user_id;
+
+-- Bug or bypass means all data is exposed!
+select * from orders;  -- Returns ALL orders
+```
+
+**Correct (database-enforced RLS):**
+
+```sql
+-- Enable RLS on the table
+alter table orders enable row level security;
+
+-- Create policy for users to see only their orders
+create policy orders_user_policy on orders
+  for all
+  using (user_id = current_setting('app.current_user_id')::bigint);
+
+-- Force RLS even for table owners
+alter table orders force row level security;
+
+-- Set user context and query
+set app.current_user_id = '123';
+select * from orders;  -- Only returns orders for user 123
+```
+
+Policy for authenticated role:
+
+```sql
+create policy orders_user_policy on orders
+  for all
+  to authenticated
+  using (user_id = auth.uid());
+```
+
+Reference: [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)

package/core/.agents/skills/supabase-postgres-best-practices/references/security-rls-performance.md

@@ -0,0 +1,57 @@
+---
+title: Optimize RLS Policies for Performance
+impact: HIGH
+impactDescription: 5-10x faster RLS queries with proper patterns
+tags: rls, performance, security, optimization
+---
+
+## Optimize RLS Policies for Performance
+
+Poorly written RLS policies can cause severe performance issues. Use subqueries and indexes strategically.
+
+**Incorrect (function called for every row):**
+
+```sql
+create policy orders_policy on orders
+  using (auth.uid() = user_id);  -- auth.uid() called per row!
+
+-- With 1M rows, auth.uid() is called 1M times
+```
+
+**Correct (wrap functions in SELECT):**
+
+```sql
+create policy orders_policy on orders
+  using ((select auth.uid()) = user_id);  -- Called once, cached
+
+-- 100x+ faster on large tables
+```
+
+Use security definer functions for complex checks:
+
+```sql
+-- Create helper function (runs as definer, bypasses RLS)
+create or replace function is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select is_team_member(team_id)));
+```
+
+Always add indexes on columns used in RLS policies:
+
+```sql
+create index orders_user_id_idx on orders (user_id);
+```
+
+Reference: [RLS Performance](https://supabase.com/docs/guides/database/postgres/row-level-security#rls-performance-recommendations)

package/core/.agents/skills/typesafe-ai/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TypeSafe AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/core/.agents/skills/typesafe-ai/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: typesafe-ai
+license: MIT
+description: >
+  Build AI-powered software with TypeSafe: small units of AI intelligence you
+  can use like programming primitives. Its System One models, including Jev,
+  turn natural language and application state into typed judgments and
+  probabilities that code can combine. Use when a feature needs programmable
+  common sense, when brainstorming what AI could make possible in an app, or
+  when an LLM prompt-and-parse step could become a structured decision.
+  Applications include routing, ranking, extraction, verification, and
+  interactive experiences; these are starting points, not the limits.
+  Read live docs and cookbooks to find useful patterns and discover new combinations.
+---
+
+# Build with TypeSafe
+
+TypeSafe makes units of AI intelligence usable like programming primitives: small
+judgments you can compose into larger capabilities. Its **System One models** return
+fast, focused judgments that software can consume directly. **Jev** is TypeSafe's
+flagship and first System One model. It understands natural language and returns
+typed answers and probabilities rather
+than generating text or reasoning explanations. Code owns the workflow; the model
+supplies programmable common sense where ordinary code needs semantic understanding.
+
+## Read the live docs
+
+**The live TypeSafe docs are the source of truth. Read them as part of the task.**
+This skill gives direction; the docs carry current concepts, prompting guidance,
+API contracts, SDK usage, models, limits, and worked examples.
+
+- Start with the [documentation index](https://docs.typesafe.ai/llms.txt) to discover
+  relevant pages and cookbooks. Use targeted reads rather than loading the entire site.
+- Mintlify serves Markdown by appending `.md` to a page path, for example
+  [how to build with TypeSafe](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md).
+  Follow links from the index; convert extensionless documentation page links to
+  `.md` when useful. Resolve relative links against `https://docs.typesafe.ai`.
+- Before writing an integration, read the current API or chosen SDK page and the
+  question guidance relevant to the design. For a new workflow, also inspect the
+  closest cookbook: it often shows a better decomposition than a generic classifier.
+- If the index is unavailable, use the direct links below or the site's navigation.
+  If Markdown fetching fails, try the normal page. If live access is unavailable,
+  use available local docs or installed SDK types, state that limitation, and avoid
+  inventing version-dependent details.
+
+| Task | Start here; follow the relevant details |
+| --- | --- |
+| Understand the programming model | [System One](https://docs.typesafe.ai/concepts/system-one.md), [building guide](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md) |
+| Explore what to build | [Use-case map](https://docs.typesafe.ai/concepts/use-case-map.md), then relevant cookbooks from the index |
+| Prepare inputs and questions | [State](https://docs.typesafe.ai/concepts/state.md), [primitives](https://docs.typesafe.ai/primitives.md), then the chosen primitive's page |
+| Decide how to handle uncertainty | [Confidence](https://docs.typesafe.ai/confidence.md) |
+| Write API code | [HTTP API](https://docs.typesafe.ai/api.md), [Python SDK](https://docs.typesafe.ai/sdk/python.md), or [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript.md) |
+| Update an older integration | [Migration guide](https://docs.typesafe.ai/migrating-to-v1.md) and the installed SDK's current reference |
+
+## Find the useful shape
+
+Start from the behavior the user wants: what will the application show, select,
+change, or hand off? Work backward to the judgments it needs. Keep known rules,
+calculations, exact lookups, and execution in code. Preserve the user's chosen stack
+and scope; add TypeSafe where semantic understanding helps.
+
+When brainstorming or choosing an architecture, consider more than classification.
+The patterns below are starting points: combine primitives around the user's goal,
+including ideas that do not fit an established recipe.
+
+- **Route and fill known arguments.** A request can select a handler and its typed
+  parameters. Ask useful branch-specific questions up front and consume only the
+  relevant answers. Explore [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md)
+  and [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out.md).
+- **Select instead of generate.** Find candidate values or source spans in code,
+  use a judgment to select the intended one, then copy or normalize it. Code can
+  also assemble source text into a formatted document or reading guide. Explore
+  [value extraction](https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook.md)
+  and [structure recovery](https://docs.typesafe.ai/cookbooks/autoformat.md).
+- **Find and judge evidence.** Retrieve candidates, compare their relevance to a
+  query, and select useful context. Explore [reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md)
+  and [hierarchical classification](https://docs.typesafe.ai/cookbooks/hierarchical_classification.md).
+- **Turn judgments into reusable data.** Score dimensions once, then let code or
+  user controls change weights, thresholds, rankings, and views. With labeled
+  outcomes, those signals can become classical ML features. Explore
+  [composite scoring](https://docs.typesafe.ai/patterns/composite-scoring.md) and
+  [feature discovery](https://docs.typesafe.ai/cookbooks/autoresearch_feature_discovery.md).
+- **Verify and escalate.** Check specific claims or fields against their evidence;
+  send uncertain or failing cases to a person or reasoning model. Explore
+  [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md) and
+  [extraction cascades](https://docs.typesafe.ai/cookbooks/sde_cascade.md).
+- **Respond to changing state.** Code can retain goals and observations while fresh
+  judgments guide the next bounded step. Keep inferred state distinct from observed
+  facts, and check freshness before applying a result to a changed situation.
+
+For open-ended requests, offer the few directions that best serve the user's goal
+and recommend a starting point. For a concrete request, choose the relevant pattern
+and build; a brainstorm is not a mandatory detour.
+
+## Design the judgments
+
+Choose by what the answer means, then read the relevant primitive page:
+
+| Need | Primitive | Important distinction |
+| --- | --- | --- |
+| One of a defined set | [Choice](https://docs.typesafe.ai/primitives/choice.md) | Picks one option; its distribution compares competing options |
+| Whether a condition holds | [Noul](https://docs.typesafe.ai/primitives/noul.md) | Probability of yes; no separate confidence; use one per label when several may apply |
+| Degree along a described dimension | [Score](https://docs.typesafe.ai/primitives/score.md) | Probability-weighted position on ordered levels; use comparable per-item Scores for graded ranking |
+
+Give each question enough relevant **state** to answer: source text, identities,
+relationships, policies, and current facts. Prefer named JSON fields when context
+has several parts. Put the judgment in **instructions** and define its possible
+answers in **criteria**. Question IDs are for code and are not sent to the model;
+include complete meaning in the question. Reference nested state with backticked
+paths such as `ticket.messages[0].text`.
+
+Ask one narrow, coherent judgment per question. Split independently useful dimensions,
+without destroying the relationship being judged. A bounded action selection or
+contextual interpretation is valid; atomic does not mean literal fact extraction
+or a one-sentence limit. Strings work for simple questions. Use structured objects
+or arrays when definitions, contrasts, exclusions, or examples clarify instructions
+or criteria. Score levels must describe concrete situations and stand on their own.
+
+Keep the needed answers available. Include a no-match outcome when nothing may fit;
+use a separate presence judgment when it is independently useful. For source-value
+selection, check candidate coverage: the model cannot choose an omitted value.
+
+## Compose and verify
+
+**Ask independent questions over the same state together**, including useful
+speculative questions. They run in parallel and cannot see one another's answers.
+State each speculative premise explicitly; code consumes the applicable answers.
+A second request is warranted when an earlier answer is needed to fetch evidence,
+construct new state, or determine the next options. Extra questions still use tokens;
+measure actual request budgets, cost, and end-to-end latency.
+
+Use probabilities and confidence to guide behavior, with thresholds evaluated on
+the user's data and consequences. Choice/Score confidence summarizes distribution
+concentration, not overall workflow correctness or permission to act. A Noul near
+0.5 means similar probability for yes and no, not medium intensity. Several
+acceptable alternatives can also spread probability; low confidence need not
+invalidate a harmless preference choice. Ignore uncertainty on unused branches.
+
+Keep policy explicit and raw judgments reusable. Weighted scores suit compensating
+preferences; an “any serious violation” rule needs separate conditions. Changing a
+weight or display filter need not rerun inference when evidence and question meanings
+are unchanged. Typed output guarantees the interface, not truth. System One models
+are trained for calibrated decisions; validate their performance in the target domain.
+
+Test representative cases and the resulting application behavior. For failures,
+inspect the exact state, questions, candidates, answers, composition, and observed
+outcome. Separate missing evidence, model errors, code errors, and service failures.
+Treat cookbook thresholds and demo results as examples to evaluate, not universal
+rules or permanent model limitations. Keep API credentials server-side in web apps.