@agent-native/core 0.152.1 → 0.153.0

package/corpus/templates/analytics/.agents/skills/feature-flags/SKILL.md

@@ -1,169 +0,0 @@
----
-name: feature-flags
-description: >-
-  Declare, evaluate, manage, and remove framework feature flags. Use when
-  shipping a capability gradually, targeting users or organizations, or
-  replacing a compile-time rollout switch with a production-safe runtime flag.
-scope: dev
-metadata:
-  internal: true
----
-
-# Feature Flags
-
-A feature flag is a boolean declared in app code, evaluated locally by Core,
-and managed from the Analytics fleet control plane. Code owns whether a flag
-exists. Runtime settings own only its rollout state.
-
-Flags let an app deploy dormant code and turn it on in the real environment
-without another deployment. They are not experiments: do not add variants,
-hypotheses, conversion metrics, exposure tracking, or lifecycle states.
-
-## When to use one
-
-Use a flag for a reversible rollout of a user-facing capability whose dormant
-code is safe to deploy. Flags are useful for production dogfooding, exact-user
-or organization pilots, and deterministic percentage rollouts.
-
-Do not use a flag for authentication, authorization, secrets, audit enablement,
-SSR cache behavior, or another security boundary. Client hiding is presentation
-only; every guarded server action must evaluate the same registered flag.
-
-## Agent workflow
-
-### 1. Declare
-
-Keep definitions in a shared TypeScript module so server and client code use the
-same stable key. Flags are boolean and default-off.
-
-```ts
-import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
-
-export const FULL_APP_BUILDING = defineFeatureFlag({
-  key: "full-app-building",
-  displayName: "Full app building",
-  description: "Create and edit Fusion-backed applications.",
-});
-```
-
-Keys are immutable, never reused, and contain only letters, numbers, dots,
-underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
-definitions or rollout rows from Analytics.
-
-### 2. Register
-
-Register app definitions from a Nitro plugin before actions are discovered.
-Do not add app-specific flags to a Core registry.
-
-```ts
-import { createFeatureFlagsPlugin } from "@agent-native/core/server";
-
-import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
-
-export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
-```
-
-### 3. Guard server and client
-
-The server action is the enforcement boundary:
-
-```ts
-import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
-
-run: async (args, ctx) => {
-  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
-    throw new Error("Full app building is not enabled for this account.");
-  }
-  // guarded operation
-}
-```
-
-Use the client hook only to hide or reveal hydrated UI:
-
-```tsx
-import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
-
-const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
-return enabled ? <FullAppOption /> : null;
-```
-
-The client hook intentionally returns false while loading or for an unknown
-flag. Never replace that fail-closed behavior with app-local bucketing or a
-compile-time fallback. Never evaluate personalized flags in the public SSR
-shell; it is shared and cached for every visitor.
-
-### 4. Verify and roll out
-
-1. Verify the off path before changing rollout state.
-2. Confirm the registered flag appears in **Analytics → Feature flags** for the
-   app and is Off by default.
-3. Use **Enable for me** for initial production dogfood.
-4. Expand to exact emails, organization IDs, or a percentage only from
-   Analytics.
-5. Confirm the client presentation and authoritative server action agree.
-
-## Management contract
-
-Core mounts three actions in registered apps:
-
-| Action | Purpose |
-| --- | --- |
-| `get-feature-flags` | Return the current caller's evaluated boolean values. |
-| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
-| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
-
-Analytics calls the app-local operator actions through narrowly scoped A2A
-delegation. Tokens require an exact audience, organization, scope, operator
-role, and audit correlation id. Management is permission-checked and audited
-by the target app. Never manage flags through generic settings routes, raw SQL,
-or per-app toggle UIs.
-
-## Rollout semantics
-
-The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
-as `off`, `rules`, and `on`.
-
-Targeted rules combine exact normalized emails, exact organization IDs, and a
-percentage with OR semantics. Exact matches are checked first. Percentage
-buckets use Core's stable hash of the flag key and authenticated user identity;
-anonymous callers fail closed. Raising a percentage preserves the users already
-included at a lower percentage. Do not implement bucketing in app code.
-
-Unknown definitions, missing state, malformed state, storage errors, and
-evaluation errors all return the code default (`false` in v1). Explicit Off
-wins over every target; Everyone enables every authenticated caller.
-
-## Remove a flag
-
-After a rollout is permanent:
-
-1. Replace guarded branches with the chosen behavior.
-2. Delete the server and client gates.
-3. Delete the definition and registration entry.
-4. Verify the flag disappears from the Analytics fleet.
-5. Remove stale tests and rollout instructions.
-
-A permanent flag is just an if statement with a pension plan.
-
-## Verification checklist
-
-- Unknown and unregistered keys evaluate false.
-- UI hiding and server enforcement use the same registered key.
-- Exact-user, organization, deterministic percentage, Everyone, and Off paths
-  have focused tests.
-- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
-- Unauthorized callers cannot list targeting details or mutate flags.
-- Mutations are atomic, read back stored state, emit refresh, and appear in the
-  audit log with the flag key.
-- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
-  and unreachable directory apps honestly.
-- Future agents can find this skill from root `AGENTS.md`, and
-  `pnpm guard:workspace-skills` passes after syncing generated copies.
-
-## Related skills
-
-- **adding-a-feature** — preserve UI/action/instruction/application-state parity
-- **actions** — define and call guarded app operations
-- **audit-log** — inspect automatic action mutation history
-- **reliable-mutations** — make rollout changes atomic and provable
-- **security** — keep security controls out of feature flags

package/corpus/templates/analytics/.agents/skills/upgrade-agent-native/SKILL.md

@@ -1,127 +0,0 @@
----
-name: upgrade-agent-native
-description: >-
-  Bring an older Agent Native app or workspace current. Use when updating
-  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
-  override core/dispatch packages to make an old branch run.
-scope: dev
-metadata:
-  internal: true
----
-
-# Upgrade Agent Native
-
-## Rule
-
-When an older Agent Native app/branch needs to run on current packages, use
-`agent-native upgrade`. Never "fix" upgrade breakage with
-`pnpm patch`, `pnpm patch-commit`, `pnpm.patchedDependencies`,
-`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patch artifacts,
-or edits under `node_modules/@agent-native/*` — especially not against
-`@agent-native/core` or `@agent-native/dispatch`.
-
-## Why
-
-Agents often respond to a failed core bump by inventing framework patches and
-dispatch behavior overrides. That hides the real app-level break, drifts from
-upstream, and makes the next upgrade worse. The supported path is bump →
-install → refresh scaffold skills → verify, then fix **app** code only.
-
-## How
-
-1. **Preview migration codemods first**
-
-   ```bash
-   npx @agent-native/core@latest upgrade --codemods
-   ```
-
-   Codemods are preview-by-default: read the diff before applying it. Do not
-   manually edit imports before running this command; the migration manifest is
-   the source of truth for renamed specifiers and symbols.
-
-2. **Apply the reviewed codemods, then run the upgrade**
-
-   ```bash
-   npx @agent-native/core@latest upgrade --codemods --yes
-   npx @agent-native/core@latest upgrade
-   ```
-
-   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
-   `agent-native upgrade`.
-
-   What it does:
-
-   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
-   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
-   - Runs the package manager install
-   - Rewrites those pins to the exact versions the install resolved, so the
-     committed manifest names one release instead of re-resolving next install
-   - Runs `skills update scaffold --project`
-   - Runs `typecheck` when the project has that script
-
-3. **Pull upstream template changes (optional, separate from the bump)**
-
-   `agent-native upgrade` moves package versions. It never touches files that
-   were copied out of a template at scaffold time, so template fixes and
-   improvements do not arrive with a bump.
-
-   ```bash
-   agent-native template status        # recorded ref vs latest, drift counts
-   agent-native template diff          # what upstream changed, read-only
-   agent-native template sync          # 3-way merge it into the app
-   ```
-
-   `sync` defaults to the ref matching the installed `@agent-native/core`, so
-   run it after `upgrade`. It merges per file against a pristine baseline
-   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
-   did not touch are left alone, and real collisions get conflict markers.
-   After resolving markers, run `agent-native template accept` — the baseline
-   deliberately does not advance past an unresolved merge.
-
-   Apps scaffolded before provenance existed have no baseline. Create one
-   with `agent-native template baseline` before the first sync.
-
-4. **If upgrade or typecheck fails**
-
-   - Read the concrete error
-   - Fix **app** source, actions, config, or env — not framework packages
-   - Re-run `agent-native upgrade` or `pnpm typecheck`
-   - Stop and ask the user if you cannot fix the app-level error
-
-   Intentional app-level UI customization is a separate workflow. Read
-   `customizing-agent-native` when the product needs to own a selectively
-   copied component; do not use that path to reproduce framework runtime
-   behavior or hide version skew.
-
-5. **Dry-run / partial runs**
-
-   ```bash
-   agent-native upgrade --dry-run
-   agent-native upgrade --skip-verify
-   agent-native upgrade --skip-install   # package.json bumps only
-   agent-native doctor --only migration-manifest
-   ```
-
-   `migration-manifest` has no opt-out. Run it in CI before upgrading to find
-   imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
-   to preview the supported rewrite.
-
-## Don't
-
-- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
-  `patchedDependencies` for any `@agent-native/*` package
-- Don't run `pnpm patch` or `pnpm patch-commit`, or commit files under
-  `patches/`, for any dependency
-- Don't edit `node_modules/@agent-native/core` or
-  `node_modules/@agent-native/dispatch`
-- Don't invent local "dispatch behavior" shims to paper over version skew
-- Don't keep iterating with more framework patches after a failed install
-- Don't skip `skills update scaffold --project` after a core bump (the
-  upgrade command does this for you)
-
-## Related Skills
-
-- **self-modifying-code** — Tier 4: framework packages are off limits
-- **agent-native-docs** — version-matched docs after the bump
-- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
-- **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/assets/.agents/skills/capture-learnings/SKILL.md

@@ -1,89 +0,0 @@
----
-name: capture-learnings
-description: >-
-  Capture and apply accumulated knowledge via structured memory. Use when the
-  user gives feedback, shares preferences, corrects a mistake, or when you
-  discover something worth remembering for future conversations.
-user-invocable: false
-metadata:
-  internal: true
----
-
-# Capture Learnings
-
-This is background knowledge, not a slash command. **Organization learnings and your personal memory index are loaded at the start of every conversation, including Slack/integration turns.** Capture durable context proactively when you learn something worth remembering.
-
-## How to Read & Write Memories
-
-Memories are stored as **resources** in the SQL database, not as files on disk.
-
-- **Team/organization knowledge:** shared `LEARNINGS.md`. Read it first, merge the new fact, then write the full updated file with the `resources` tool using `scope: "shared"`. Shared scope resolves to the active organization; it must never leak to another organization in the same deployment.
-- **Personal knowledge:** `memory/MEMORY.md` plus `memory/<name>.md`, written with `save-memory`.
-
-- **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
-- **Read a memory:** `resource-read --path memory/<name>.md`
-- **Delete a memory:** `delete-memory --name <name>`
-- **List all memories:** `resource-list --prefix memory/`
-
-## Memory Types
-
-| Type | Use for |
-|------|---------|
-| `user` | Preferences, role, personal context, contacts |
-| `feedback` | Corrections, confirmed approaches, things to avoid or repeat |
-| `project` | Ongoing work context, decisions, deadlines, status |
-| `reference` | Pointers to external systems, URLs, API details |
-
-## When to Capture
-
-### Team and organization knowledge (`LEARNINGS.md`, shared scope)
-- Canonical destinations and workflows (for example, which Content database receives a type of Slack request)
-- Required intake fields, ownership, prioritization conventions, metric definitions, and approved terminology
-- Durable external references that the whole team needs, including the canonical page/database URL
-- Corrections or decisions that should affect every organization member's future Slack and app conversations
-
-Store the fact and a concise provenance link when available. Do not paste full private conversations, customer data, credentials, or secrets into learnings. Put stable always-on policy in shared `AGENTS.md`; put learned facts and evolving conventions in shared `LEARNINGS.md`.
-
-### User Preferences & Memory (`user`)
-- **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
-- **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
-- **Workflow preferences** — "always CC my assistant", "I like to review before sending"
-- **Role and expertise** — "I'm a data scientist", "new to React"
-
-### Feedback & Corrections (`feedback`)
-- **Corrections** — user says "no, do it this way" → capture the right way
-- **Confirmed approaches** — user validates a non-obvious choice ("yes, that's perfect")
-- **Repeated friction** — you hit the same issue twice; save it
-
-### Project Context (`project`)
-- **Ongoing work** — who is doing what, why, by when
-- **Decisions** — why something is done a certain way
-- **Status** — current state of initiatives
-
-### References (`reference`)
-- **External systems** — "bugs are tracked in Linear project INGEST"
-- **URLs** — dashboards, documentation, tools
-- **API quirks** — undocumented behavior, version-specific gotchas
-
-### Don't Capture
-- Things obvious from reading the code
-- Standard language/framework behavior
-- Temporary debugging notes
-- Anything already in AGENTS.md, shared LEARNINGS.md, or skills
-- Ephemeral task details (use tasks/plans instead)
-
-## Key Rules
-
-1. **Save proactively — don't ask permission.** When you learn something durable, save it immediately at the correct scope.
-2. **Choose scope by audience.** Organization workflow or reference → shared `LEARNINGS.md`; one person's preference/context → personal memory.
-3. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
-4. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
-5. **Keep descriptions concise** — the index is loaded every conversation
-6. **Memories are SQL-backed** — they persist across sessions and are not in git; still minimize sensitive content
-
-## Graduation
-
-When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
-- Saving a personal memory is lightweight (auto-apply, personal scope)
-- Shared LEARNINGS.md is the lightweight organization knowledge layer
-- Updating AGENTS.md or a skill is heavier (affects all users/agents)

package/corpus/templates/assets/.agents/skills/create-skill/SKILL.md

@@ -1,195 +0,0 @@
----
-name: create-skill
-description: >-
-  How to create new skills for an agent-native app. Use when adding a new
-  skill, documenting a pattern the agent should follow, or creating reusable
-  guidance for the agent.
-scope: dev
-metadata:
-  internal: true
----
-
-# Create a Skill
-
-## When to Use
-
-Create a new skill when:
-
-- There's a pattern the agent should follow repeatedly.
-- A multi-step workflow needs reliable, step-by-step guidance.
-- You want to scaffold files from a template.
-
-Don't create a skill when:
-
-- The guidance already exists in another skill — extend it instead.
-- You're documenting something the agent already knows (e.g., how to write
-  TypeScript).
-- It's a one-off — put it in `AGENTS.md` (for everyone) or `memory/MEMORY.md`
-  (personal, per-user). See **capture-learnings**.
-
-## Interview
-
-Before writing the skill, answer these:
-
-1. **What should this skill enable?** — The core purpose in one sentence.
-2. **Which of the four areas does it serve?** — UI, actions, skills/instructions,
-   or application state (see the **adding-a-feature** skill). Most skills are
-   about how to touch one or more of these correctly.
-3. **When should it trigger?** — Describe the situations in natural language.
-4. **Does it involve context awareness?** — Does the agent need to know what the
-   user is looking at? If so, reference the `navigation` application-state key and
-   the `view-screen` action pattern. See the **context-awareness** skill.
-5. **What type of skill?** — Pattern, Workflow, or Generator (see below).
-6. **Does it need supporting files?** — References (read-only context) or none.
-   Keep it minimal; push depth into `references/`.
-
-## Skill Types and Templates
-
-### Pattern (architectural rule)
-
-For documenting how things should be done:
-
-```markdown
----
-name: my-pattern
-description: >-
-  [Under 40 words. What it covers AND when it should trigger.]
----
-
-# [Pattern Name]
-
-## Rule
-
-[One sentence: what must be true]
-
-## Why
-
-[Why this rule exists]
-
-## How
-
-[How to follow it, with code examples]
-
-## Don't
-
-[Common violations]
-
-## Related Skills
-
-[Which skills compose with this one]
-```
-
-### Workflow (step-by-step)
-
-For multi-step implementation tasks:
-
-```markdown
----
-name: my-workflow
-description: >-
-  [Under 40 words. What it covers AND when it should trigger.]
----
-
-# [Workflow Name]
-
-## Prerequisites
-
-[What must be in place first]
-
-## Steps
-
-[Numbered steps with code examples]
-
-## Verification
-
-[How to confirm it worked]
-
-## Troubleshooting
-
-[Common issues and fixes]
-
-## Related Skills
-```
-
-### Generator (scaffolding)
-
-For creating files from templates:
-
-```markdown
----
-name: my-generator
-description: >-
-  [Under 40 words. What it covers AND when it should trigger.]
----
-
-# [Generator Name]
-
-## Usage
-
-[How to invoke — what args/inputs are needed]
-
-## What Gets Created
-
-[List of files and their purpose]
-
-## Template
-
-[The template content with placeholders]
-
-## After Generation
-
-[What to do next — wire up sync, add routes, register the action, etc.]
-
-## Related Skills
-```
-
-## Naming Conventions
-
-- Hyphen-case only: `[a-z0-9-]`, max 64 characters.
-- Pattern skills: descriptive names (`storing-data`, `delegate-to-agent`).
-- Workflow/generator skills: verb-noun (`create-skill`, `capture-learnings`).
-- The directory name must match the `name` in frontmatter.
-
-## Frontmatter Fields
-
-| Field         | Required | Value                                         |
-| ------------- | -------- | --------------------------------------------- |
-| `name`        | yes      | Hyphen-case, matches the directory name        |
-| `description` | yes      | What the skill covers AND when it triggers     |
-| `scope`       | no       | `both` (default) \| `runtime` \| `dev`         |
-
-For how to word a `description` and which `scope` a skill should get, follow
-**writing-agent-instructions** — it owns those rules.
-
-## Tips
-
-- **Keep SKILL.md lean (under ~500 lines)** — move detailed content to
-  `references/` files.
-- **Use standard markdown headings** — no XML tags or custom formats.
-
-## Anti-Patterns
-
-- **Inline LLM calls** — skills must not call LLMs directly. All AI work goes
-  through the agent chat (see **delegate-to-agent**).
-- **Introducing databases** — data lives in SQL via Drizzle (see **storing-data**).
-- **Ignoring sync** — if a skill creates data, mention wiring `useDbSync` /
-  `useActionQuery` so the UI updates (see **real-time-sync**).
-- **Pure documentation** — skills should guide action, not just explain concepts.
-
-## File Structure
-
-```
-.agents/skills/my-skill/
-├── SKILL.md              # Main skill (required)
-└── references/           # Optional supporting context
-    └── detailed-guide.md
-```
-
-## Related Skills
-
-- **adding-a-feature** — The four-area model every skill ultimately serves.
-- **writing-agent-instructions** — How to write AGENTS.md and skills well for
-  apps and templates you ship to others.
-- **capture-learnings** — When a learning graduates to reusable guidance, create
-  a skill; one-offs go to `AGENTS.md` or `memory/MEMORY.md`.
-- **self-modifying-code** — The agent can create new skills (Tier 2 modification).