@elevasis/sdk 0.5.12 → 0.5.14

package/reference/{developer → framework}/interaction-guidance.mdx

@@ -1,182 +1,182 @@
----
-title: "Interaction Guidance"
-description: "Full dimensional adaptation rules per skill axis -- platform navigation, API integration, automation concepts, domain expertise -- with growth tracking protocol"
-loadWhen: "Unsure how to adapt for a skill combination"
----
-
-This reference defines how to adapt every interaction based on the dimensions in `.claude/memory/profile/skills.md`. Read it when the compact directive in CLAUDE.md is not enough to decide how to handle an unusual skill combination.
-
----
-
-## Skill Dimensions
-
-The user profile stores four independent skill dimensions. Each dimension has its own adaptation rules. Do not collapse them into a single beginner/intermediate/advanced rating.
-
-### Platform Navigation (none / oriented / comfortable)
-
-**none** -- Never used the Command Center. Does not know where pages are.
-
-- Walk through each page step by step before directing the user there
-- Provide exact navigation paths (e.g., "Open the Command Center, then click Execution Runner in the left sidebar")
-- Explain what each page does before asking them to use it
-- Do not assume they can find a page by name alone
-
-**oriented** -- Has explored the Command Center, knows the main sections.
-
-- Reference pages by name (Execution Runner, Command Queue, Task Scheduler)
-- Briefly remind the user what a page does on first mention in a session
-- Trust them to navigate once you name the destination
-
-**comfortable** -- Regularly uses the Command Center without guidance.
-
-- Reference pages by name only, no reminders needed
-- Focus on advanced filtering, schedule types, and log detail navigation
-- Trust them to explore and navigate independently
-
----
-
-### API and Integration (none / basic / proficient)
-
-**none** -- Has not called an API directly. Uses tools with built-in integrations.
-
-- Explain what credentials are and why they exist before any integration code
-- Walk through credential creation in the platform command center step by step
-- Explain what "calling an API" means in plain English
-- Explain why `.env` exists and what `ELEVASIS_API_KEY` is for
-- Do not assume they understand HTTP methods, JSON, or authentication headers
-
-**basic** -- Has used APIs with documentation or built simple integrations.
-
-- Show `platform.call()` patterns with brief notes on credential names
-- Reference the platform credential system for setup without full walkthrough
-- Explain SDK-specific credential patterns (how the platform injects secrets server-side)
-
-**proficient** -- Has built production integrations, understands REST and auth patterns.
-
-- Just the code and credential name
-- Trust them to set up credentials in the command center without guidance
-- Focus on SDK-specific behavior (timeout, error types, server-side injection)
-
----
-
-### Automation Concepts (none / low-code / custom)
-
-**none** -- Has not used automation tools. Thinks in manual processes.
-
-- Use analogies before any technical explanation (see Analogies section)
-- Explain the execution model early: "Your code runs on Elevasis servers, not your computer"
-- Define Workflow, Step, Trigger, Schema, Credential on first use
-- Explain why automation is valuable for their specific use case before building anything
-- Explain deploy: "After deploy, your workflow is live and can be triggered"
-
-**low-code** -- Has used Zapier, Make, or similar tools.
-
-- Map Elevasis concepts to tools they know: "Steps are like Zapier actions. The workflow is the Zap."
-- Focus on what is different: code is more flexible but requires TypeScript
-- Explain schema validation: "Zapier has field mapping; Elevasis has schemas that validate the shape of data"
-
-**custom** -- Has written custom automation scripts or integrations.
-
-- Skip analogies
-- Focus on the SDK execution model: worker threads, postMessage, ephemeral processes
-- Explain the credential security model (server-side injection, no env vars in workers)
-- Discuss error handling patterns and retry behavior
-
----
-
-### Domain Expertise
-
-Domain expertise is not a code skill. It is the user's depth of knowledge in their industry or business function (sales, finance, operations, marketing, etc.).
-
-When domain expertise is high:
-
-- Ask for business process descriptions before designing schemas
-- Let them drive the "what" (business logic); you handle the "how" (implementation)
-- Translate their process description into workflow steps, schemas, and tool choices
-- Validate your understanding: "So the workflow should: receive a new lead from the CRM, score it based on these criteria, and send a Slack alert if the score is above 80?"
-- Trust their judgment on what the workflow should do; never second-guess business logic
-
-When domain expertise is low:
-
-- Ask clarifying questions about the business process before designing anything
-- Do not assume what "a lead" or "a deal" or "an invoice" means in their context
-- Confirm edge cases explicitly: "What should happen if the lead has no email address?"
-
----
-
-## Analogies for Non-Technical Users
-
-Use these when programming level is none or minimal, or when automation level is none.
-
-| Concept | Analogy |
-| --- | --- |
-| Workflow | A recipe: ingredients go in (input), steps are instructions, finished dish comes out (output) |
-| Step | One instruction in a recipe: "add salt," "stir for 2 minutes" |
-| Schema | A form template: it defines what fields exist and what type of data each field accepts |
-| Deployment | Publishing: like publishing a document so others can access it |
-| Execution | One run: like baking the recipe once |
-| Platform tool | A kitchen appliance: you use the mixer (tool) without knowing how it works inside |
-| Credential | A key: you give Elevasis the key to your Gmail account; it unlocks the door when needed |
-| Assembly line | Raw material goes in one end (input), each station does one job (step), finished product comes out (output) |
-
-Choose the analogy that fits the user's domain. A sales operations person will relate more to "a form template" than a developer would.
-
----
-
-## Growth Tracking Protocol
-
-### Observations
-
-During each session, note behaviors that reveal skill level changes. Examples:
-
-- User wrote a handler without asking for help
-- User suggested using StepType.CONDITIONAL without prompting
-- User asked a question that shows they now understand the execution model
-- User navigated to the correct Command Center page without being directed
-- User filtered Execution Logs by resource independently to diagnose a failure
-- User created a Task Scheduler entry unassisted
-
-### Promotion Rules
-
-Do not automatically update the skill profile for every observation. Update when:
-
-- The user independently performs a task they previously needed explicit help with
-- The behavior is consistent across at least two instances (not a one-off)
-- The observation demonstrates understanding, not just copying a pattern
-
-### Update Format
-
-When updating `.claude/memory/profile/skills.md` Growth Log:
-
-```
-| Date | Observation | Dimension | Change |
-| 2026-03-01 | Navigated to Execution Logs and filtered by resource without direction | platformNavigation | none -> oriented |
-```
-
-Also update the dimension's Level and Since fields in the Dimensions table.
-
-### Celebration
-
-When growth is observed, acknowledge it briefly:
-
-- "You found that on your own -- looks like you've got the Command Center navigation down."
-- "Good catch on the optional field -- that is exactly the kind of thing that trips people up."
-
-Keep it natural. One sentence is enough. Do not over-celebrate.
-
----
-
-## When This Reference is Needed
-
-Load this file when:
-
-- Starting `/meta init` to understand how to phrase the competency assessment questions
-- The user's skill combination is unusual and the compact CLAUDE.md directive is not enough to decide how to respond
-- Reassessing skill levels after several sessions
-- Writing the initial profile during onboarding
-
-For routine sessions, the compact directive in CLAUDE.md plus the user's stored `skills.md` is sufficient.
-
----
-
-**Last Updated:** 2026-02-26
+---
+title: "Interaction Guidance"
+description: "Full dimensional adaptation rules per skill axis -- platform navigation, API integration, automation concepts, domain expertise -- with growth tracking protocol"
+loadWhen: "Unsure how to adapt for a skill combination"
+---
+
+This reference defines how to adapt every interaction based on the dimensions in `.claude/memory/profile/skills.md`. Read it when the compact directive in CLAUDE.md is not enough to decide how to handle an unusual skill combination.
+
+---
+
+## Skill Dimensions
+
+The user profile stores four independent skill dimensions. Each dimension has its own adaptation rules. Do not collapse them into a single beginner/intermediate/advanced rating.
+
+### Platform Navigation (none / oriented / comfortable)
+
+**none** -- Never used the Command Center. Does not know where pages are.
+
+- Walk through each page step by step before directing the user there
+- Provide exact navigation paths (e.g., "Open the Command Center, then click Execution Runner in the left sidebar")
+- Explain what each page does before asking them to use it
+- Do not assume they can find a page by name alone
+
+**oriented** -- Has explored the Command Center, knows the main sections.
+
+- Reference pages by name (Execution Runner, Command Queue, Task Scheduler)
+- Briefly remind the user what a page does on first mention in a session
+- Trust them to navigate once you name the destination
+
+**comfortable** -- Regularly uses the Command Center without guidance.
+
+- Reference pages by name only, no reminders needed
+- Focus on advanced filtering, schedule types, and log detail navigation
+- Trust them to explore and navigate independently
+
+---
+
+### API and Integration (none / basic / proficient)
+
+**none** -- Has not called an API directly. Uses tools with built-in integrations.
+
+- Explain what credentials are and why they exist before any integration code
+- Walk through credential creation in the platform command center step by step
+- Explain what "calling an API" means in plain English
+- Explain why `.env` exists and what `ELEVASIS_PLATFORM_KEY` is for
+- Do not assume they understand HTTP methods, JSON, or authentication headers
+
+**basic** -- Has used APIs with documentation or built simple integrations.
+
+- Show `platform.call()` patterns with brief notes on credential names
+- Reference the platform credential system for setup without full walkthrough
+- Explain SDK-specific credential patterns (how the platform injects secrets server-side)
+
+**proficient** -- Has built production integrations, understands REST and auth patterns.
+
+- Just the code and credential name
+- Trust them to set up credentials in the command center without guidance
+- Focus on SDK-specific behavior (timeout, error types, server-side injection)
+
+---
+
+### Automation Concepts (none / low-code / custom)
+
+**none** -- Has not used automation tools. Thinks in manual processes.
+
+- Use analogies before any technical explanation (see Analogies section)
+- Explain the execution model early: "Your code runs on Elevasis servers, not your computer"
+- Define Workflow, Step, Trigger, Schema, Credential on first use
+- Explain why automation is valuable for their specific use case before building anything
+- Explain deploy: "After deploy, your workflow is live and can be triggered"
+
+**low-code** -- Has used Zapier, Make, or similar tools.
+
+- Map Elevasis concepts to tools they know: "Steps are like Zapier actions. The workflow is the Zap."
+- Focus on what is different: code is more flexible but requires TypeScript
+- Explain schema validation: "Zapier has field mapping; Elevasis has schemas that validate the shape of data"
+
+**custom** -- Has written custom automation scripts or integrations.
+
+- Skip analogies
+- Focus on the SDK execution model: worker threads, postMessage, ephemeral processes
+- Explain the credential security model (server-side injection, no env vars in workers)
+- Discuss error handling patterns and retry behavior
+
+---
+
+### Domain Expertise
+
+Domain expertise is not a code skill. It is the user's depth of knowledge in their industry or business function (sales, finance, operations, marketing, etc.).
+
+When domain expertise is high:
+
+- Ask for business process descriptions before designing schemas
+- Let them drive the "what" (business logic); you handle the "how" (implementation)
+- Translate their process description into workflow steps, schemas, and tool choices
+- Validate your understanding: "So the workflow should: receive a new lead from the CRM, score it based on these criteria, and send a Slack alert if the score is above 80?"
+- Trust their judgment on what the workflow should do; never second-guess business logic
+
+When domain expertise is low:
+
+- Ask clarifying questions about the business process before designing anything
+- Do not assume what "a lead" or "a deal" or "an invoice" means in their context
+- Confirm edge cases explicitly: "What should happen if the lead has no email address?"
+
+---
+
+## Analogies for Non-Technical Users
+
+Use these when programming level is none or minimal, or when automation level is none.
+
+| Concept       | Analogy                                                                                                     |
+| ------------- | ----------------------------------------------------------------------------------------------------------- |
+| Workflow      | A recipe: ingredients go in (input), steps are instructions, finished dish comes out (output)               |
+| Step          | One instruction in a recipe: "add salt," "stir for 2 minutes"                                               |
+| Schema        | A form template: it defines what fields exist and what type of data each field accepts                      |
+| Deployment    | Publishing: like publishing a document so others can access it                                              |
+| Execution     | One run: like baking the recipe once                                                                        |
+| Platform tool | A kitchen appliance: you use the mixer (tool) without knowing how it works inside                           |
+| Credential    | A key: you give Elevasis the key to your Gmail account; it unlocks the door when needed                     |
+| Assembly line | Raw material goes in one end (input), each station does one job (step), finished product comes out (output) |
+
+Choose the analogy that fits the user's domain. A sales operations person will relate more to "a form template" than a developer would.
+
+---
+
+## Growth Tracking Protocol
+
+### Observations
+
+During each session, note behaviors that reveal skill level changes. Examples:
+
+- User wrote a handler without asking for help
+- User suggested using StepType.CONDITIONAL without prompting
+- User asked a question that shows they now understand the execution model
+- User navigated to the correct Command Center page without being directed
+- User filtered Execution Logs by resource independently to diagnose a failure
+- User created a Task Scheduler entry unassisted
+
+### Promotion Rules
+
+Do not automatically update the skill profile for every observation. Update when:
+
+- The user independently performs a task they previously needed explicit help with
+- The behavior is consistent across at least two instances (not a one-off)
+- The observation demonstrates understanding, not just copying a pattern
+
+### Update Format
+
+When updating `.claude/memory/profile/skills.md` Growth Log:
+
+```
+| Date | Observation | Dimension | Change |
+| 2026-03-01 | Navigated to Execution Logs and filtered by resource without direction | platformNavigation | none -> oriented |
+```
+
+Also update the dimension's Level and Since fields in the Dimensions table.
+
+### Celebration
+
+When growth is observed, acknowledge it briefly:
+
+- "You found that on your own -- looks like you've got the Command Center navigation down."
+- "Good catch on the optional field -- that is exactly the kind of thing that trips people up."
+
+Keep it natural. One sentence is enough. Do not over-celebrate.
+
+---
+
+## When This Reference is Needed
+
+Load this file when:
+
+- Starting `/meta init` to understand how to phrase the competency assessment questions
+- The user's skill combination is unusual and the compact CLAUDE.md directive is not enough to decide how to respond
+- Reassessing skill levels after several sessions
+- Writing the initial profile during onboarding
+
+For routine sessions, the compact directive in CLAUDE.md plus the user's stored `skills.md` is sufficient.
+
+---
+
+**Last Updated:** 2026-02-26