Best practices

Satia is an AI-Native Business Operating System. Whether you are operating from Sati or from an external AI agent via MCP (Claude Code, Cursor, Codex, Windsurf, or Antigravity), following the right architectural sequence is the difference between a fragile/slow setup and a fast, reliable, auditable business operation.

---

1. Mandatory Building Sequence: Database-First, Exterior-Last

Never start by building a custom view (custom_views), a Python automation script (automation_scripts), or an external channel integration before the underlying business tables and columns exist and are validated in the database.

Strict 5-Step Construction Order:

1. Step 1 — Inspect the Pre-Loaded Workspace Context:
   • Your active workspace context (business tables in business_tables_catalog, column schemas in unified_schema_markdown, document folders in knowledge_folders_directory, transactional agents in transactional_agents_directory, and internal staff) is already injected into your instructions. Use it directly without running redundant exploratory queries.
2. Step 2 — Model the Database First (system_delegation__delegate_to_schema_builder):
   • If business tables, columns, relationships (relation), statuses (status), carts (line_items), or reactive calculated columns (formula / conditional ROLLUP) are missing, delegate their creation in plain natural language to the Data Modeler (system_delegation__delegate_to_schema_builder).
   • When iterating on a schema request, pass the same delegation_session_id. Once complete (or when operating via MCP), call workspace__get_context(force_refresh=True) if needed to refresh the catalog of table slugs and columns.
3. Step 3 — Seed & Validate Real Records (database__insert / database__query):
   • Insert realistic test records into the business tables using their slug and verify that relationships, line items, and reactive formulas compute the expected values.
4. Step 4 — Build Knowledge, Agents, and Internal/Mobile Views:
   • Create master playbooks and manuals in knowledge_docs (organized inside knowledge_folders).
   • Configure transactional agents (agents), their granular table/column permissions (agent_tables), and linked documents (agent_docs).
   • Build Custom Views and Micro-Apps (custom_views and shared_view_links via database__insert, database__update, and database__patch_text) following the Satia Design System. Remember that Custom Views run both on the web platform and natively inside the Satia Mobile App (window.satia.native).
5. Step 5 — Connect External Integrations Last (Automations, Webhooks, Channels):
   • Once tables, formulas, and views work internally, write and test external integration scripts (automation__test_script → automation__save_script).

---

2. Golden Rule: Prefer Asynchronous Event Automations (event) over Synchronous Agent Tools

One of the most common design mistakes is attaching multiple synchronous agent_tools to a conversational agent (WhatsApp, Instagram, Web) that call slow external APIs (electronic invoicing, legacy ERPs, email delivery, PDF generation) in the middle of a live customer conversation.

Why Table Event Automations (trigger_type="event") Are Superior:

When SHOULD You Use an Agent Tool (agent_tools)?

Use agent_tools only when the conversational agent requires the live response from an external system within the exact same turn in order to reply to the customer (for example: checking live shipping carrier tracking not stored in Satia, or generating an instant checkout link when not driven by a table status change). For everything else (CRM sync, issuing electronic invoices, sending Slack/email alerts, updating external ERP inventory), have the agent write to the Satia business table and trigger a trigger_type="event" automation.

---

3. Native Reactive Formulas (formula & Conditional ROLLUP) vs. Python Scripts

• Never use a Python automation script (automation_scripts) to calculate order totals, taxes, customer balances, stock counters, or status badges that can be expressed with a formula column.
• Satia's reactive formula engine runs natively inside the database and client UI: it recalculates in 0 ms on every insert or update, with zero async queues and zero risk of infinite update loops.
• If a table has a shopping cart (line_items), its subtotal, tax, and total must be formula columns (e.g., sum({{productos.total}})).
• If you need to aggregate or look up values across related tables (e.g., a customer's accumulated balance, total non-canceled orders, or a contracted plan price), always delegate a cross-table ROLLUP (including conditional filters such as estado != 'cancelado') to system_delegation__delegate_to_schema_builder.

---

4. First-Class Business Tables (slug)

In Satia, every business module (clientes, pedidos, productos, citas, facturas, etc.) operates as a first-class SQL table identified by its slug:

• ALWAYS use the business table's slug (or table_slug when linking views and schedules) and its declared column names directly across SQL (database__query, database__insert, database__update), Python (db.query, db.get, db.filter, db.insert, db.update), and Custom Views (window.satia.getEntities, createEntity, updateEntity).
• Write all queries and mutations referencing only the columns listed in the table's schema (e.g., SELECT id, name, total, estado FROM pedidos WHERE estado = 'pagado'). Workspace isolation and role permissions are enforced automatically.

---

5. Surgical Editing & Context Economy

1. Inspect Without Flooding Context (database__inspect_text):
   • Whenever you need to inspect view code (custom_views.code_content), automation scripts (automation_scripts.code), custom tool code (agent_tools.script_code), agent personalities (agents.personality), or long documents (knowledge_docs.content), never run SELECT code_content or paginate with OFFSET loops. Use database__inspect_text with search_pattern or start_line/end_line.
2. Patch Instead of Rewriting (database__patch_text):
   • To modify existing views, scripts, agent personalities, or documents, always use database__patch_text. It is faster, consumes a fraction of the tokens, and prevents accidental truncation.
3. Human Attribution (user_prompt):
   • Always pass the user's original instruction in user_prompt on every write or delete call so platform_audit_logs records an accurate audit trail of who requested each change and why.

---

6. Official Web Platform Routes Reference

When guiding the user to perform an action in the Satia web interface, always point them to the exact route (never invent non-existent settings pages):