@agent-native/core 0.152.1 → 0.153.0

package/src/templates/workspace-core/.agents/skills/turn-into-app/references/spreadsheet-source.md

@@ -0,0 +1,148 @@
+# Spreadsheet source review
+
+Use this reference after a workbook upload or Google Sheets link is supplied to
+`/turn-into-app`. It defines the bounded review contract before app creation.
+
+## 1. Establish the source boundary
+
+Record the source before interpreting it:
+
+| Field        | Record                                                                            |
+| ------------ | --------------------------------------------------------------------------------- |
+| Source kind  | `xlsx`, `xls`, `csv`, or Google Sheets URL                                        |
+| Provenance   | Original file name or spreadsheet ID and URL; never credentials or workbook bytes |
+| Access       | Upload preview, authenticated provider read, or unavailable                       |
+| Coverage     | Worksheet names, selected range(s), row/column bounds, and sample counts          |
+| Completeness | Complete within the requested bound, partial, truncated, unreadable, or empty     |
+| Refresh      | One-time snapshot or live refreshable source                                      |
+
+For an uploaded XLS/XLSX file, the framework preview contains worksheet names,
+dimensions, and representative displayed values within bounds. It does not
+currently preserve cell fills or font colors in that text preview. Treat the
+original workbook as the formatting authority only when a tool actually returns
+cell formatting metadata. Never describe a text-only upload as style-verified.
+
+For a Google Sheets URL:
+
+1. Parse the spreadsheet ID and preserve the original URL as provenance.
+2. Use the authenticated `google_drive` provider path. Inspect
+   `provider-api-catalog` first, use `provider-api-docs` if the endpoint or
+   fields are uncertain, and then call `provider-api-request`.
+3. Read spreadsheet metadata and only bounded worksheet/range data. Request
+   formatting metadata when the I/O decision depends on colors, including
+   `userEnteredFormat.backgroundColor` and
+   `userEnteredFormat.textFormat.foregroundColor` where the provider supports
+   it. Do not use a public export URL to bypass access.
+4. Preserve the spreadsheet ID, worksheet title, A1 range, account/connection
+   choice without secrets, row limits, and refresh behavior in the brief.
+
+Keep provider responses bounded. For large sheets, stage or save the response
+and reduce it with the available dataset/code tools. A failed page, truncated
+response, or unavailable connection is not an empty sheet.
+
+## 2. Infer cells and ranges, then show the evidence
+
+Classify source material into three separate buckets. Include representative
+cell addresses or ranges and the evidence behind each classification.
+
+| Bucket             | Default signal                                                                                                     | App treatment                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Inputs             | Yellow cell background, editable assumptions, user-entered constants, or labels such as `assumption` / `driver`    | Editable controls or bounded source parameters                         |
+| Outputs            | Blue text, formula-derived result cells, summary blocks, or labels such as `forecast` / `recommendation`           | Read-only results, charts, recommendations, exports, or review actions |
+| Static historicals | Black text used intentionally for prior-period/source records, raw rows, or labels such as `actual` / `historical` | Read-only context; never turn into editable inputs by default          |
+
+These are conventions, not permission to guess. A default black font with no
+explicit style metadata is not enough to label a range as historical. Resolve
+conflicts using labels, formulas, neighboring headers, repeated patterns, and
+the user's stated goal. If the evidence still conflicts, lower confidence and
+ask the user to confirm the proposed mapping.
+
+Keep source cells and app behavior distinct:
+
+- `Source inputs` are the workbook cells or ranges the user is expected to
+  change or refresh.
+- `Source outputs` are the workbook cells or ranges the source already derives
+  or presents.
+- `Static historicals` are context the app may filter, compare, or summarize,
+  but should not edit.
+- `App outputs` are the new app's visible results, saved records, exports,
+  alerts, or downstream handoffs. Do not invent these until the repeatable job
+  or user confirmation makes them clear.
+
+## 3. Offer candidate apps, not a tab dump
+
+Group related worksheets into candidate repeatable jobs. A candidate should
+have a recognizable user, trigger, inputs, transformation or judgment, and
+outputs. Utility tabs such as lookups, raw imports, instructions, pivots, and
+calculation helpers can support a candidate without becoming destinations.
+
+Present a compact Q&A review with multi-select options. In generated app code,
+use `askUserQuestion` from `@agent-native/core/client/agent-chat` with
+`allowMultiple: true`, stable candidate IDs as option values, and
+`allowFreeText: true` for corrections. It renders inline in the agent panel;
+do not build a custom modal. Each option should fit in a scannable row or
+choice card:
+
+```text
+Candidate: Pipeline forecast
+Uses: Assumptions, Historical Pipeline, Forecast
+Inputs: yellow assumptions in Assumptions!B4:B12 (high confidence)
+Outputs: blue forecast summary in Forecast!B3:H10 (medium confidence)
+Historical context: Historical Pipeline!A1:K500
+Question: Confirm that forecast assumptions should be editable?
+```
+
+Mark the strongest recommendation with `recommended: true`, but do not silently
+select it. Let the user select none, one, or several candidates, correct a
+proposed tab/range, or answer the unresolved question. Keep each question to
+2-4 grouped candidate jobs; for a larger workbook, group related tabs into
+jobs rather than showing a tab dump or asking a separate question for every
+worksheet. If there is only one high-confidence candidate, keep the review
+compact and ask for confirmation only when the I/O mapping or source access is
+unclear.
+
+When several candidates are selected, pass a stable candidate ID, display name,
+source worksheet/ranges, I/O mapping, confidence, and confirmation status for
+each. The generated app should expose them as separate named left-navigation
+destinations or tabs, not merge them into an opaque dashboard and not create a
+separate workspace app for every worksheet.
+
+## 4. Confirm before building or publishing
+
+The confirmation view is a source-integrity checkpoint, not a product-design
+questionnaire. Show:
+
+- the source file or spreadsheet ID and snapshot/live choice;
+- selected candidate destinations and their source tabs/ranges;
+- editable inputs, read-only outputs, and static historical context;
+- the evidence and confidence for each mapping;
+- truncation, unreadable, missing-connection, and refresh limitations;
+- the app outputs/actions that will be created.
+
+Use clear actions such as `Confirm and build`, `Edit mapping`, and `Use a
+different source`. If the host has a structured question or multi-select UI,
+use it. Otherwise, ask one concise assistant message that presents the same
+options and requires an explicit confirmation/correction before handoff.
+
+After confirmation, the online host may call
+`start-workspace-app-creation`; the Builder run itself remains autonomous and
+must record any remaining non-blocking assumptions. In a local generated app,
+persist the confirmation state in SQL/application state and keep the user on
+the review surface while the agent builds. Never claim a full import, live
+refresh, or output write until the corresponding source/action has succeeded.
+
+## 5. Failure and recovery states
+
+Keep these states distinct in the review and in the handoff:
+
+- `unreadable` - parser/provider could not read the source;
+- `partial` - only some worksheets, ranges, rows, or pages were read;
+- `truncated` - the bounded preview ended before full coverage;
+- `empty` - the requested readable range contains no values;
+- `not-connected` - authenticated Google access is required but unavailable;
+- `confirmed` - the user approved the candidate and I/O mapping.
+
+For unreadable or not-connected sources, request a CSV/XLSX export or the
+required connection. For partial or truncated sources, continue only with a
+clearly bounded snapshot or ask for a narrower range. Do not coerce any of
+these states into a successful empty source.

package/src/templates/workspace-core/.agents/skills/workspace-conventions/SKILL.md

@@ -20,8 +20,9 @@ resources, or looking up framework APIs.
 Read `agent-native-docs` for the lookup workflow (`framework-search` first, then
 the focused `docs-search` / `source-search` readers, and the `rg` fallback).
 
-The workspace-specific slugs it does not list are `workspace`,
-`multi-app-workspace`, and `feature-flags`. Use package docs for framework APIs,
+The workspace-specific slugs it does not list are `workspace` and
+`multi-app-workspace`. Feature flags and other specialized workflows are
+optional; read their skill only when the app uses them. Use package docs for framework APIs,
 the package corpus for reusable framework/template patterns, and this
 `AGENTS.md` plus `.agents/skills/` for workspace-specific conventions.
 

package/src/templates/workspace-core/AGENTS.md

@@ -11,16 +11,22 @@ Read the matching skill in `.agents/skills/` before working in that area.
 | Skill | Read before |
 | --- | --- |
 | `workspace-conventions` | Shared vs app-owned code, file/blob storage, env and secrets, scratch files, Dispatch Resources |
-| `adding-workspace-apps` | Creating, scaffolding, mounting, or branding an app under `apps/<app-name>` |
+| `adding-a-feature` | Adding a cross-cutting feature or capability |
 | `agent-native-docs` | Looking up version-matched framework docs, slugs, or the bundled source corpus |
 | `agent-native-toolkit` | Building workspace or agent UI, app chrome, settings, sharing, or collaboration |
 | `customizing-agent-native` | Adapting, overriding, or ejecting shared framework UI |
 | `delegate-to-agent` | Building agent-driven UI or any "AI" feature |
 | `actions` | Adding or changing an app operation the agent and UI share |
-| `composable-mini-apps` | Cross-app workflows, headless mini-apps, and A2A handoffs |
+| `frontend-design` | Any user-facing UI change |
+| `real-time-sync` | Keeping UI queries current after agent or action writes |
 | `shadcn-ui` | Adding, updating, or debugging a shadcn/ui primitive |
 | `security`, `sharing` | Access scoping, ownable data, and sharing user-authored resources |
-| `automations` | Event-triggered or scheduled background work (with `recurring-jobs`) |
+| `secrets`, `storing-data` | Credentials or persisted application data |
+| `self-modifying-code` | Agent-editable app source and protected paths |
+
+This is the complete default inherited set. Feature flags, translations,
+changelogs, integrations, automations, A2A workflows, and release/promotion
+helpers stay available as opt-in skills for the apps that use them.
 
 ## Shared Context
 

package/src/templates/workspace-root/AGENTS.md

@@ -6,6 +6,12 @@ in `apps/<app>/AGENTS.md`; shared cross-app behavior belongs in
 The root `.agents/skills` path points at the shared package's skills so local
 coding agents can discover the same workspace-wide guidance from the root.
 
+The inherited skill set is intentionally small: actions, data, security,
+secrets, sync, shared UI, agent delegation, and workspace conventions. Skills
+for feature flags, translations, changelogs, providers, automations, release
+workflows, and other specialized work are opt-in. Add an optional skill to the
+workspace core or the app that needs it; do not copy it into every app.
+
 ## Framework Docs Lookup
 
 Version-matched Agent Native docs ship with `@agent-native/core` in
@@ -22,7 +28,8 @@ template patterns ships in `node_modules/@agent-native/core/corpus`.
   and `node_modules/@agent-native/core/dist/` for framework internals.
 - For advanced workspace features, start with `workspace`, `multi-app-workspace`,
   `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
-  `external-agents`, `mcp-protocol`, `feature-flags`, `sharing`, and `security`.
+  `external-agents`, `mcp-protocol`, `sharing`, and `security`. These are
+  optional skills; read them only when the app or workspace uses that feature.
 
 Use package docs for framework APIs, the package corpus for reusable
 template patterns, and `packages/shared/AGENTS.md` plus
@@ -45,6 +52,24 @@ After a manual core bump only, `pnpm skills:update` (or
 refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 `.claude/skills` compatibility links.
 
+## Lightweight defaults
+
+New apps use English as the source locale and do not generate changelog
+entries. To opt into additional translations or changelog generation, edit
+`agent-native.config.ts` at the workspace root:
+
+```ts
+import { defineAgentNativeConfig } from "@agent-native/core";
+
+export default defineAgentNativeConfig({
+  translations: { locales: ["en-US", "es-ES"] },
+  changelog: { enabled: true },
+});
+```
+
+An app-local config can override the workspace policy when only one app needs
+an additional locale or changelog.
+
 ## Core Agent Rule
 
 - All AI/LLM behavior goes through the app's agent chat. UI and server code

package/src/templates/workspace-root/agent-native.config.ts

@@ -0,0 +1,8 @@
+import { defineAgentNativeConfig } from "@agent-native/core";
+
+export default defineAgentNativeConfig({
+  // English is the source locale. Add supported locale codes here when this
+  // workspace is intentionally translated.
+  translations: { locales: ["en-US"] },
+  changelog: { enabled: false },
+});

package/corpus/templates/analytics/.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/analytics/.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).