@getfrontline/cli 1.0.1 → 1.0.4

package/dist/skills/crm-setup/SKILL.md

@@ -6,15 +6,25 @@ description: >
     between entities, adding pipeline stages, populating data, and querying
     across related objects. Use as a reference when building any multi-entity
     business workflow from scratch.
+    IMPORTANT: Before designing new entities or fields, always read the
+    `frontline-internals` skill to understand what the system already handles
+    automatically (activity sync, consolidation, built-in objects).
 allowed-tools: Bash(frontline:*)
 ---
 
 # Building a CRM with the Frontline CLI
 
+> [!IMPORTANT]
+> **Read the [`frontline-internals`](../frontline-internals/SKILL.md) skill first.**
+> It describes what the platform already handles automatically — including
+> activity synchronization (emails, conversations, …) and periodic
+> consolidation of fields like `Last Interaction`. Designing entities that
+> duplicate built-in behaviour leads to split history and inconsistent data.
+
 This skill walks through building a complete CRM system: Companies, Contacts,
 and Deals — with relations, pipeline stages, record types, and views.
 
-> The built-in `sor__companies`, `sor__people`, and `sor__deals` objects already
+> The built-in `companies`, `people`, and `deals` objects already
 > exist. This guide uses **custom objects** to show how to build everything from
 > scratch, but the same patterns apply when extending existing objects.
 
@@ -65,6 +75,8 @@ Use `object create` for business entities and `table create` for simple data.
 # Create a new "Embarques" table
 frontline table create embarques --data '{
   "displayName": "Embarques",
+  "emoji": "truck",
+  "icon_color": "orange",
   "columns": [
     { "name": "Nombre", "type": "string", "metadata": { "format": "text" } }
   ]
@@ -73,6 +85,8 @@ frontline table create embarques --data '{
 # Create a new "Pedidos" table
 frontline table create pedidos --data '{
   "displayName": "Pedidos",
+  "emoji": "package",
+  "icon_color": "blue",
   "columns": [
     { "name": "Nombre", "type": "string", "metadata": { "format": "text" } }
   ]
@@ -82,9 +96,9 @@ frontline table create pedidos --data '{
 The system also ships with these core objects:
 
 ```
-sor__companies  — Companies
-sor__people     — People (contacts)
-sor__deals      — Deals (sales pipeline)
+companies  — Companies
+people     — People (contacts)
+deals      — Deals (sales pipeline)
 ```
 
 Verify they exist:
@@ -93,21 +107,35 @@ Verify they exist:
 frontline object list
 ```
 
+### Setting Icons on Existing Objects/Tables
+
+```bash
+frontline object update deals --data '{"emoji": "handshake", "icon_color": "emerald"}'
+frontline table update embarques --data '{"emoji": "delivery", "icon_color": "teal"}'
+```
+
+### Available Icon Colors
+
+Use the `icon_color` field with a **color name** (case-insensitive):
+
+`red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`,
+`cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `pink`, `rose`
+
 ## Step 2 — Inspect & Extend the Schema
 
 ### View current fields
 
 ```bash
-frontline object field list sor__companies
-frontline object field list sor__people
-frontline object field list sor__deals
+frontline object field list companies
+frontline object field list people
+frontline object field list deals
 ```
 
 ### Add custom fields
 
 ```bash
 # Add a "Lead Source" select field to People
-frontline object field create sor__people --data '{
+frontline object field create people --data '{
   "name": "Lead Source",
   "type": "select",
   "metadata": { "mode": "singleSelect" }
@@ -115,20 +143,20 @@ frontline object field create sor__people --data '{
 # → Returns: { id: 15, name: "Lead Source", type: "select", ... }
 
 # Add options to the new field (use the field ID from above)
-frontline object option create sor__people 15 --data '{"name": "Website", "color": "Sky"}'
-frontline object option create sor__people 15 --data '{"name": "Referral", "color": "Emerald"}'
-frontline object option create sor__people 15 --data '{"name": "Cold Outreach", "color": "Gray"}'
-frontline object option create sor__people 15 --data '{"name": "Event", "color": "Lavender"}'
+frontline object option create people 15 --data '{"name": "Website", "color": "Sky"}'
+frontline object option create people 15 --data '{"name": "Referral", "color": "Emerald"}'
+frontline object option create people 15 --data '{"name": "Cold Outreach", "color": "Gray"}'
+frontline object option create people 15 --data '{"name": "Event", "color": "Lavender"}'
 
 # Add a "Probability %" number field to Deals
-frontline object field create sor__deals --data '{
+frontline object field create deals --data '{
   "name": "Probability",
   "type": "number",
   "metadata": {}
 }'
 
 # Add a "Next Follow-up" date field to Deals
-frontline object field create sor__deals --data '{
+frontline object field create deals --data '{
   "name": "Next Follow-up",
   "type": "dateOnly",
   "metadata": {}
@@ -140,13 +168,13 @@ frontline object field create sor__deals --data '{
 The built-in objects already have relations defined:
 
 ```bash
-frontline object schema sor__people
-# → relations: [{ name: "companies", target: "sor__companies", mode: "multi" }]
+frontline object schema people
+# → relations: [{ name: "companies", target: "companies", mode: "multi" }]
 
-frontline object schema sor__deals
+frontline object schema deals
 # → relations: [
-#     { name: "people", target: "sor__people", mode: "multi" },
-#     { name: "company", target: "sor__companies", mode: "single" }
+#     { name: "people", target: "people", mode: "multi" },
+#     { name: "company", target: "companies", mode: "single" }
 #   ]
 ```
 
@@ -157,14 +185,14 @@ The `name` field is what you use in all relation commands.
 ### Create companies
 
 ```bash
-frontline object record create sor__companies --data '{
+frontline object record create companies --data '{
   "Name": "Acme Corp",
   "Domain": "acme.com",
   "Primary Location": "New York, USA"
 }'
 # → { id: "6625aaa...", ... }
 
-frontline object record create sor__companies --data '{
+frontline object record create companies --data '{
   "Name": "TechStart Inc",
   "Domain": "techstart.io",
   "Primary Location": "San Francisco, USA"
@@ -175,7 +203,7 @@ frontline object record create sor__companies --data '{
 ### Create contacts
 
 ```bash
-frontline object record create sor__people --data '{
+frontline object record create people --data '{
   "First Name": "Alice",
   "Last Name": "Johnson",
   "Email": "alice@acme.com",
@@ -184,7 +212,7 @@ frontline object record create sor__people --data '{
 }'
 # → { id: "6625ccc...", ... }
 
-frontline object record create sor__people --data '{
+frontline object record create people --data '{
   "First Name": "Bob",
   "Last Name": "Smith",
   "Email": "bob@techstart.io",
@@ -196,10 +224,10 @@ frontline object record create sor__people --data '{
 ### Create deals
 
 ```bash
-# Use option IDs from `frontline object field list sor__deals`
+# Use option IDs from `frontline object field list deals`
 # Stage options: 1=Lead, 2=In Progress, 3=Won, 4=Lost
 
-frontline object record create sor__deals --data '{
+frontline object record create deals --data '{
   "Name": "Acme Enterprise License",
   "Stage": [2],
   "Value": 150000
@@ -213,36 +241,36 @@ frontline object record create sor__deals --data '{
 
 ```bash
 # Alice works at Acme
-frontline object relation link sor__people 6625ccc... Companies 6625aaa...
+frontline object relation link people 6625ccc... Companies 6625aaa...
 
 # Bob works at TechStart
-frontline object relation link sor__people 6625ddd... Companies 6625bbb...
+frontline object relation link people 6625ddd... Companies 6625bbb...
 ```
 
 ### Link deal → company and deal → person
 
 ```bash
 # The Acme deal belongs to Acme Corp
-frontline object relation link sor__deals 6625eee... Company 6625aaa...
+frontline object relation link deals 6625eee... Company 6625aaa...
 
 # Alice is the contact for this deal
-frontline object relation link sor__deals 6625eee... People 6625ccc...
+frontline object relation link deals 6625eee... People 6625ccc...
 ```
 
 ### Verify links
 
 ```bash
 # What company does Alice belong to?
-frontline object relation get sor__people 6625ccc... Companies
+frontline object relation get people 6625ccc... Companies
 
 # Who are the contacts for the Acme deal?
-frontline object relation get sor__deals 6625eee... People
+frontline object relation get deals 6625eee... People
 
 # Which deals belong to Acme Corp? (reverse lookup)
-frontline object relation find-by sor__deals Company 6625aaa...
+frontline object relation find-by deals Company 6625aaa...
 
 # Which people work at Acme Corp? (reverse lookup)
-frontline object relation find-by sor__people Companies 6625aaa...
+frontline object relation find-by people Companies 6625aaa...
 ```
 
 ## Step 6 — Set Up Pipeline Views
@@ -251,10 +279,10 @@ frontline object relation find-by sor__people Companies 6625aaa...
 
 ```bash
 # Get the field IDs to include in each record type
-frontline object field list sor__deals
+frontline object field list deals
 # → Use the IDs for Name, Stage, Value, People, Company
 
-frontline object record-type create sor__deals --data '{
+frontline object record-type create deals --data '{
   "name": "active_pipeline",
   "displayName": "Active Pipeline",
   "columnIds": [1, 2, 3, 5, 8]
@@ -267,14 +295,14 @@ frontline object record-type create sor__deals --data '{
 ```bash
 # Use the Stage field ID for grouping (e.g., field ID 2)
 # Create directly on the object (no record type needed)
-frontline object view create sor__deals --data '{
+frontline object view create deals --data '{
   "name": "Pipeline Board",
   "type": "KANBAN",
   "metadata": { "groupingColumnId": 2 }
 }'
 
 # Or scoped to a specific record type with --record-type <id>
-frontline object view create sor__deals --record-type 7 --data '{
+frontline object view create deals --record-type 7 --data '{
   "name": "Pipeline Board",
   "type": "KANBAN",
   "metadata": { "groupingColumnId": 2 }
@@ -289,13 +317,13 @@ Refine your views to show only the most important information:
 
 ```bash
 # Set order of columns/fields
-frontline object view update sor__deals <view-id> --column-order "Name, Stage, Value, Company"
+frontline object view update deals <view-id> --column-order "Name, Stage, Value, Company"
 
 # Hide less relevant fields
-frontline object view update sor__deals <view-id> --hidden-columns "Created At, Updated At"
+frontline object view update deals <view-id> --hidden-columns "Created At, Updated At"
 
 # Order fields in the record creation dialog
-frontline object view update sor__deals <view-id> --dialog-field-order "Name, Stage, Value, Probability"
+frontline object view update deals <view-id> --dialog-field-order "Name, Stage, Value, Probability"
 ```
 
 ## Step 8 — Query Your CRM
@@ -303,7 +331,7 @@ frontline object view update sor__deals <view-id> --dialog-field-order "Name, St
 ### Find high-value deals
 
 ```bash
-frontline object record list sor__deals --query '{
+frontline object record list deals --query '{
   "operator": "and",
   "conditions": [
     { "path": "[Value]", "operator": "gte", "value": 50000 },
@@ -315,7 +343,7 @@ frontline object record list sor__deals --query '{
 ### Find contacts with no company
 
 ```bash
-frontline object record list sor__people --query '{
+frontline object record list people --query '{
   "path": "[Companies]", "operator": "isNull"
 }'
 ```
@@ -323,29 +351,29 @@ frontline object record list sor__people --query '{
 ### Search across fields
 
 ```bash
-frontline object record list sor__people --search "alice"
-frontline object record list sor__companies --search "tech"
+frontline object record list people --search "alice"
+frontline object record list companies --search "tech"
 ```
 
 ### Find all contacts at a specific company
 
 ```bash
-frontline object relation find-by sor__people Companies <company-id>
+frontline object relation find-by people Companies <company-id>
 ```
 
 ## Step 8 — Export & Backup
 
 ```bash
 # Export all deals to spreadsheet
-frontline object export xlsx sor__deals --output deals_report.xlsx
+frontline object export xlsx deals --output deals_report.xlsx
 
 # Export filtered data (only won deals)
-frontline object export csv sor__deals \
+frontline object export csv deals \
   --query '{"path": "[Stage]", "operator": "containsAny", "value": [3]}' \
   --output won_deals.csv
 
 # Export all contacts
-frontline object export xlsx sor__people --output contacts_backup.xlsx
+frontline object export xlsx people --output contacts_backup.xlsx
 ```
 
 ## Quick Command Reference

package/dist/skills/crud-operations/SKILL.md

@@ -269,10 +269,10 @@ Create a new record type with a kanban view for a deals pipeline:
 
 ```bash
 # 1. Check current fields
-frontline object field list sor__deals
+frontline object field list deals
 
 # 2. Create a record type (returns record_type_id)
-frontline object record-type create sor__deals --data '{
+frontline object record-type create deals --data '{
   "name": "enterprise",
   "displayName": "Enterprise Deals",
   "columnIds": [1, 2, 5, 8]

package/dist/skills/export-and-delete/SKILL.md

@@ -23,10 +23,10 @@ frontline object export xlsx <name> [--output file.xlsx]
 
 ```bash
 # Export all people
-frontline object export xlsx sor__people
+frontline object export xlsx people
 
 # Export with filter (high-value deals only)
-frontline object export xlsx sor__deals \
+frontline object export xlsx deals \
   --query '{"path": "[Amount]", "operator": "gte", "value": 10000}' \
   --output big_deals.xlsx
 
@@ -46,7 +46,7 @@ frontline object export csv <name> [--output file.csv]
 
 ```bash
 # Export all records as CSV
-frontline object export csv sor__people --output people_backup.csv
+frontline object export csv people --output people_backup.csv
 ```
 
 ### Default Output
@@ -86,11 +86,11 @@ Always export before deleting:
 
 ```bash
 # 1. Export everything
-frontline object export xlsx sor__legacy_deals --output legacy_deals_backup.xlsx
+frontline object export xlsx legacy_deals --output legacy_deals_backup.xlsx
 
 # 2. Verify the export file exists and looks right
 ls -la legacy_deals_backup.xlsx
 
 # 3. Delete the object
-frontline object delete sor__legacy_deals
+frontline object delete legacy_deals
 ```

package/dist/skills/files/SKILL.md

@@ -55,16 +55,16 @@ frontline table file delete <table> <file-id>
 
 ```bash
 # 1. Find the row
-frontline object row list sor__deals --search "Acme Corp"
+frontline object row list deals --search "Acme Corp"
 # → row ID = 6625abc123def456
 
 # 2. List attached files
-frontline object file list sor__deals 6625abc123def456
+frontline object file list deals 6625abc123def456
 # → [{ id: 15, originalName: "contract_v2.pdf", size: 245000, ... }]
 
 # 3. Download a file
-frontline object file download sor__deals 15 --output ./contract_v2.pdf
+frontline object file download deals 15 --output ./contract_v2.pdf
 
 # 4. Delete an outdated file
-frontline object file delete sor__deals 15
+frontline object file delete deals 15
 ```

package/dist/skills/filter-and-query/SKILL.md

@@ -17,18 +17,18 @@ The `frontline table row list` and `frontline object record list` commands accep
 
 ```bash
 # Simple text search across all fields
-frontline object record list sor__people --search "john"
+frontline object record list people --search "john"
 
 # Filter by a single condition
 # TIP: Use 'frontline object field list <name>' to find field names and tag IDs
-frontline object record list sor__deals --query '{
+frontline object record list deals --query '{
   "path": "[Amount]",
   "operator": "gte",
   "value": 10000
 }'
 
 # Multiple conditions (AND)
-frontline object record list sor__deals --query '{
+frontline object record list deals --query '{
   "operator": "and",
   "conditions": [
     { "path": "[Status]", "operator": "containsAny", "value": [1, 2] },
@@ -37,7 +37,7 @@ frontline object record list sor__deals --query '{
 }'
 
 # Sort results
-frontline object record list sor__people --sort '[{"path": "[Last Name]", "type": "asc"}]'
+frontline object record list people --sort '[{"path": "[Last Name]", "type": "asc"}]'
 ```
 
 ## Path Format
@@ -176,8 +176,8 @@ frontline table row list my_table --page 1 --page-size 50
 ## Filter by Record Type (objects only)
 
 ```bash
-frontline object record list sor__people --record-type lead
-frontline object record list sor__deals --record-type "all"
+frontline object record list people --record-type lead
+frontline object record list deals --record-type "all"
 ```
 
 ## Full Example
@@ -185,7 +185,7 @@ frontline object record list sor__deals --record-type "all"
 Find all open deals worth over $10k, owned by a specific company, sorted by amount:
 
 ```bash
-frontline object record list sor__deals \
+frontline object record list deals \
   --query '{
     "operator": "and",
     "conditions": [

package/dist/skills/frontline-internals/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: frontline-internals
+description: >
+    Internal workings of the Frontline platform: how the base CRM objects
+    (Company, Deals, People, Tickets) relate to each other, how activity
+    synchronization works automatically for People and Companies, and how
+    periodic consolidation keeps CRM records up to date. Read this skill
+    before designing new entities or fields to avoid duplicating behavior
+    that the system already handles automatically.
+allowed-tools: Bash(frontline:*)
+---
+
+# Frontline Internal System Mechanics
+
+Understanding how Frontline works internally is critical **before** designing
+new objects, fields, or relations. Many common CRM needs are already handled
+automatically by the platform.
+
+---
+
+## 1. Base Objects and Their Relationships
+
+Frontline ships with four core objects that form the foundation of every
+account. They are pre-provisioned and cannot be deleted.
+
+```
+companies   — Organizations / accounts
+people      — Individual contacts
+deals       — Sales opportunities
+tickets     — Support or service requests
+```
+
+### Built-in Relations
+
+```
+People  →  Companies   (many-to-many)
+Deals   →  People      (many-to-many)
+Deals   →  Company     (many-to-one)
+Tickets →  People      (many-to-many)
+Tickets →  Company     (many-to-one)
+```
+
+> **Before creating a new entity**, check whether it fits naturally as a
+> custom object linked to one of these four. Most vertical use cases (leads,
+> vendors, partners, subscribers) are best modeled as extensions of People or
+> Companies rather than standalone objects.
+
+---
+
+## 2. Automatic Activity Synchronization
+
+When an account grants the required permissions, Frontline automatically
+captures and attaches **activity records** to People and Company objects.
+You do **not** need to create these manually or build pipelines to collect them.
+
+### Activity Types (peopleActivity / companyActivity)
+
+Each activity record has a `type` field that identifies the source:
+
+| Type            | Description                                                  |
+| --------------- | ------------------------------------------------------------ |
+| `email`         | Inbound or outbound emails linked to the contact or company  |
+| `conversation`  | Chat/messaging interactions (Slack, etc.)                    |
+| _(more coming)_ | The system is designed to receive additional types over time |
+
+Activity records are stored as `peopleActivity` (for People) or
+`companyActivity` (for Companies) and are surfaced automatically in the
+record's activity feed.
+
+### What this means in practice
+
+- **You do not need an "Emails" table.** Emails are synced automatically.
+- **You do not need a "Conversations" table.** Those are synced automatically.
+- If you need to query or filter activities, use the activity endpoints
+  rather than creating a parallel data structure.
+
+> **Before building a new data pipeline or table to capture interactions**,
+> verify whether that interaction type is already handled by the activity
+> sync. Adding a duplicate table leads to split history and inconsistent data.
+
+---
+
+## 3. Periodic Consolidation
+
+Beyond real-time activity sync, Frontline runs **periodic consolidation jobs**
+that aggregate and summarize information at the People and Company level.
+
+### What gets consolidated
+
+- **Last Interaction** — The most recent interaction date across all activity
+  types is computed and written to the People record. For Companies, this is
+  further propagated from all linked People: the Company's `Last Interaction`
+  always reflects the freshest interaction across any of its contacts.
+- **Profile Insights (Structured AI Assessments)** — The system evaluates the
+  state of the relationship and record data.
+    - **For People**: Sentiment (very_positive to very_negative), Engagement
+      Level (highly_engaged to at_risk), key relationship description, identified
+      Risks (e.g., churn signals), and Opportunities.
+    - **For Companies**: Connection Strength (Strong/Medium/Weak), Key People
+      discovery (stakeholders), and Company Mission extraction.
+- **Key Topics** — A list of the top 3-5 recurring themes in interactions
+  (e.g., "Pricing", "Onboarding", "Product Feedback").
+- **Summaries** — Concise, professional overviews of the person or company
+  based on all recent context.
+
+### Implications for custom fields
+
+- Do **not** build a custom "last email date" or "last activity date" field
+  and try to keep it in sync manually via hooks or external automation.
+  The system already maintains `Last Interaction` for this purpose.
+- If you need a consolidation that does not yet exist, raise it as a
+  platform request rather than building a workaround.
+
+---
+
+## 4. Design Checklist — Before Adding New Entities or Fields
+
+Use this checklist whenever you are about to create a new object, table, or field:
+
+1. **Is this already a base object?**
+   Check `frontline object list` — `companies`, `people`,
+   `deals`, `tickets` may already fit.
+
+2. **Is this interaction data?**
+   If the new entity stores emails, messages, calls, or any user-to-contact
+   interaction, check whether the activity sync already covers it before
+   building a custom table.
+
+3. **Is this a summary or aggregate?**
+   If the field would need to be recomputed based on interactions
+   (e.g., "last contacted", "interaction count"), check if periodic
+   consolidation already provides it via built-in fields.
+
+4. **Does a relation already exist?**
+   Run `frontline object schema <obj>` to inspect existing relations before
+   creating a new one. Duplicate relations cause inconsistent data.
+
+5. **Only then — extend or create.**
+   If none of the above covers the need, proceed to add a custom field
+   (see `crm-setup` skill) or create a new object/table.
+
+---
+
+## 5. Memories & Intelligent Consolidation
+
+Beyond raw activity sync, Frontline uses AI to distill important facts and
+structured data about People and Companies. This process is called
+**Consolidation**.
+
+### What are "Memories"?
+
+Memories are persistent, AI-distilled facts about a person or company that
+provide context for future interactions. Unlike activity logs, memories are
+long-lived and categorized.
+
+**Categories include:**
+
+- `DECISION`: Specific decisions made (e.g., "Decided to postpone the project until Q3").
+- `AGREEMENT`: Agreed terms or commitments (e.g., "Agreed to a 20% discount for the first year").
+- `PREFERENCE`: Personal or professional preferences (e.g., "Prefers morning meetings").
+- `RISK`: Potential issues or red flags (e.g., "Customer is frustrated with current response times").
+- `OTHER`: General facts or context (e.g., "Is a fan of the Golden State Warriors").
+
+> **Example**: Instead of searching through 50 emails to find a contact's
+> preferred communication channel, the system creates a `PREFERENCE` memory:
+> _"Prefers being contacted via WhatsApp after 6pm."_
+
+### Structured Data Extracted
+
+During periodic consolidation, the LLM extracts and updates specific data
+points to keep record profiles fresh:
+
+| Object      | Data Point           | Description / Examples                                     |
+| :---------- | :------------------- | :--------------------------------------------------------- |
+| **People**  | **Profile Insights** | Sentiment, Engagement, Risks, Opportunities, Key Topics    |
+|             | **Summary**          | Professional overview of persona and status                |
+| **Company** | **Profile Insights** | Connection Strength, Key Stakeholders, Mission             |
+|             | **Firmographics**    | Revenue, Employee count, Headquarters (from external sync) |
+
+### How this data is used
+
+1. **Intelligent Feed**: Memories and summaries are displayed in the CRM feed to
+   give users instant context without reading threads.
+2. **AI Reasoning (RAG)**: When an AI agent (or you, the developer) queries the
+   system, it retrieves these memories to generate responses that are
+   contextually aware.
+3. **Automated Triggers**: Consolidated fields (like `Last Interaction` or
+   `Connection Strength`) can trigger automated workflows.
+
+---
+
+## 6. Summary
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ WHAT FRONTLINE DOES AUTOMATICALLY                               │
+│                                                                 │
+│  • Syncs emails/conversations → people/company Activity        │
+│  • Consolidates Last Interaction & Connection Strength        │
+│                                                                 │
+│ INTELLIGENT CONSOLIDATION                                       │
+│  • Distills "Memories" (Decisions, Preferences, Risks, etc.)   │
+│  • Extracts Structured Data (Summary, Insights, Firmographics) │
+│  • Updates Vector Store for context-aware AI reasoning         │
+│                                                                 │
+│ BASE OBJECTS                                                    │
+│  companies  people  deals  tickets         │
+└─────────────────────────────────────────────────────────────────┘
+```