@getfrontline/cli 1.0.0 → 1.0.3

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.
+
+```
+standard__companies   — Organizations / accounts
+standard__people      — Individual contacts
+standard__deals       — Sales opportunities
+standard__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` — `standard__companies`, `standard__people`,
+   `standard__deals`, `standard__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                                                    │
+│  standard__companies  standard__people  standard__deals  standard__tickets         │
+└─────────────────────────────────────────────────────────────────┘
+```

package/dist/skills/max-auth/SKILL.md

@@ -1,76 +1,76 @@
----
-name: max-auth
-description: Manage Max CLI authentication — store per-user API key (synced with Frontline CLI), sign out, and inspect the active profile. Use when the user needs Max terminal auth, whoami, or clearing credentials.
----
-
-## Prerequisites
-
-- The `max` CLI must be installed (`npm i -g @frontline/cli` — provides both `frontline` and `max` binaries).
-- A **per-user API key** from the Frontline web app (Settings → API keys). The browser SSO (Firebase) flow is **paused** in the CLI; `MAX_CLI_AUTH_URL` is not required for the current flow.
-
-## How credentials work
-
-- `max auth login <api-key>` saves the same key to the **Max** store (`max-cli`) and the **Frontline** store (`frontline-cli`) under the **same profile name**, so `max` and `frontline` stay aligned.
-- `max` commands call the **Public API** (`…/public/v1/max/...`) with `Authorization: Bearer <apiKey>` (USER key, same as SoR).
-- Public API base URL: same as `frontline` — `FRONTLINE_BASE_URL`, profile `baseUrl`, or `--base-url` on each command (`max auth login --base-url …` persists it on the Frontline profile).
-- API key resolution: `--api-key` → `MAX_API_KEY` / `FRONTLINE_API_KEY` → Max profile `apiKey` → Frontline profile `apiKey` (same name).
-
-## Commands
-
-### Sign in (save API key)
-
-```bash
-max auth login <api-key> [--profile <name>] [--base-url <url>]
-```
-
-| Option             | Description                                                                                          |
-| ------------------ | ---------------------------------------------------------------------------------------------------- |
-| `<api-key>`        | Per-user API key (required argument)                                                                 |
-| `--profile <name>` | Profile to save under (default: current; if set, also switches active profile for Max and Frontline) |
-| `--base-url <url>` | Public API root for **both** `max` and `frontline` on that profile (must end with `/public/v1`)      |
-
-**Examples:**
-
-```bash
-max auth login flk_abc123
-
-max auth login flk_abc123 --profile staging \
-  --base-url https://staging-api.example.com/public/v1
-```
-
-### Sign out
-
-```bash
-max auth logout [--profile <name>] [--keep-frontline]
-```
-
-| Option             | Description                                                    |
-| ------------------ | -------------------------------------------------------------- |
-| `--profile <name>` | Profile to clear (default: current)                            |
-| `--keep-frontline` | Only clear the Max store; leave the matching Frontline profile |
-
-By default, the matching Frontline profile is removed too.
-
-### Check profile / credentials
-
-```bash
-max auth whoami [--json] [--profile <name>]
-```
-
-Shows API key preview, `maxApiBaseUrl`, whether a matching Frontline profile exists, and Max config path (no JWT decode; browser SSO is paused).
-
-### Config path
-
-```bash
-max config-path
-```
-
-## Troubleshooting
-
-- **"No API key saved for profile …"** — run `max auth login <api-key>` or `frontline auth login <api-key>` with the same `--profile`.
-- **"No Max API key found"** — same as above, or set `MAX_API_KEY` / `FRONTLINE_API_KEY`.
-- **401 on Max** — key revoked or wrong; create a new key in the app and run `max auth login` again.
-
-## Browser SSO note
-
-The legacy flow (`max auth login` with no argument, hosted page + localhost callback) is commented out in the package. To restore it later, see git history and `packages/cli/src/max/browserLogin.ts`.
+---
+name: max-auth
+description: Manage Max CLI authentication — store per-user API key (synced with Frontline CLI), sign out, and inspect the active profile. Use when the user needs Max terminal auth, whoami, or clearing credentials.
+---
+
+## Prerequisites
+
+- The `max` CLI must be installed (`npm i -g @frontline/cli` — provides both `frontline` and `max` binaries).
+- A **per-user API key** from the Frontline web app (Settings → API keys). The browser SSO (Firebase) flow is **paused** in the CLI; `MAX_CLI_AUTH_URL` is not required for the current flow.
+
+## How credentials work
+
+- `max auth login <api-key>` saves the same key to the **Max** store (`max-cli`) and the **Frontline** store (`frontline-cli`) under the **same profile name**, so `max` and `frontline` stay aligned.
+- `max` commands call the **Public API** (`…/public/v1/max/...`) with `Authorization: Bearer <apiKey>` (USER key, same as SoR).
+- Public API base URL: same as `frontline` — `FRONTLINE_BASE_URL`, profile `baseUrl`, or `--base-url` on each command (`max auth login --base-url …` persists it on the Frontline profile).
+- API key resolution: `--api-key` → `MAX_API_KEY` / `FRONTLINE_API_KEY` → Max profile `apiKey` → Frontline profile `apiKey` (same name).
+
+## Commands
+
+### Sign in (save API key)
+
+```bash
+max auth login <api-key> [--profile <name>] [--base-url <url>]
+```
+
+| Option             | Description                                                                                          |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `<api-key>`        | Per-user API key (required argument)                                                                 |
+| `--profile <name>` | Profile to save under (default: current; if set, also switches active profile for Max and Frontline) |
+| `--base-url <url>` | Public API root for **both** `max` and `frontline` on that profile (must end with `/public/v1`)      |
+
+**Examples:**
+
+```bash
+max auth login flk_abc123
+
+max auth login flk_abc123 --profile staging \
+  --base-url https://staging-api.example.com/public/v1
+```
+
+### Sign out
+
+```bash
+max auth logout [--profile <name>] [--keep-frontline]
+```
+
+| Option             | Description                                                    |
+| ------------------ | -------------------------------------------------------------- |
+| `--profile <name>` | Profile to clear (default: current)                            |
+| `--keep-frontline` | Only clear the Max store; leave the matching Frontline profile |
+
+By default, the matching Frontline profile is removed too.
+
+### Check profile / credentials
+
+```bash
+max auth whoami [--json] [--profile <name>]
+```
+
+Shows API key preview, `maxApiBaseUrl`, whether a matching Frontline profile exists, and Max config path (no JWT decode; browser SSO is paused).
+
+### Config path
+
+```bash
+max config-path
+```
+
+## Troubleshooting
+
+- **"No API key saved for profile …"** — run `max auth login <api-key>` or `frontline auth login <api-key>` with the same `--profile`.
+- **"No Max API key found"** — same as above, or set `MAX_API_KEY` / `FRONTLINE_API_KEY`.
+- **401 on Max** — key revoked or wrong; create a new key in the app and run `max auth login` again.
+
+## Browser SSO note
+
+The legacy flow (`max auth login` with no argument, hosted page + localhost callback) is commented out in the package. To restore it later, see git history and `packages/cli/src/max/browserLogin.ts`.

package/dist/skills/max-chat/SKILL.md

@@ -1,111 +1,111 @@
----
-name: max-chat
-description: Send messages to the Max AI assistant and manage conversations from the terminal. Use when the user wants to chat with Max, send a quick question, start a new conversation, or open an interactive chat session.
----
-
-## Prerequisites
-
-- The `max` CLI must be installed (`npm i -g @frontline/cli` — provides both `frontline` and `max` binaries).
-- The user must have a per-user API key saved: `max auth login <api-key>` (or `frontline auth login` on the same profile).
-
-## Commands
-
-### Quick message (shorthand)
-
-```bash
-max "Your question here"
-max --new "Start a fresh conversation"
-```
-
-This is the fastest way to send a single message to Max. It uses the last active conversation by default, or `--new` to start a fresh one.
-
-Calls the **Public API**: `POST /public/v1/max/conversations/message` (Bearer = user API key). Responses use `{ "ok": boolean, "data": ... }`. Default stdout is **one-line JSON**; no spinner lines.
-
-| Flag                   | Description                                                 |
-| ---------------------- | ----------------------------------------------------------- |
-| `--new`                | Start a new conversation instead of continuing the last one |
-| `--conversation <id>`  | Send to a specific conversation ID                          |
-| `--no-wait`            | Do not poll for the assistant reply (fire and forget)       |
-| `--timeout <seconds>`  | Max seconds to wait for assistant reply (default: 60)       |
-| `--json`               | Print only the POST response JSON (no poll)                 |
-| `--pretty`             | Print assistant plain text from `data` instead of JSON      |
-| `--profile <name>`     | Use a specific Max CLI profile                              |
-| `--base-url <url>`     | Override Public API root (…/public/v1) for this run         |
-| `--api-base-url <url>` | Deprecated alias for `--base-url`                           |
-| `--api-key <key>`      | Override per-user API key for this run                      |
-| `--debug`              | Show HTTP request/response diagnostics                      |
-
-**Example:**
-
-```bash
-# Quick question using last conversation
-max "What agents do I have?"
-
-# Start a new conversation
-max --new "Help me set up a new workflow"
-
-# Send to a specific conversation
-max --conversation 123 "Continue from here"
-```
-
-### Send a message (explicit command)
-
-```bash
-max chat send <message...> [--new] [--conversation <id>] [--json] [--debug]
-```
-
-Same as the shorthand above but under the `chat send` subcommand. Default stdout is **one-line JSON**; **`--pretty`** for assistant plain text from `data`.
-
-### Interactive chat (REPL)
-
-```bash
-max chat repl [--profile <name>] [--debug] [--timeout <seconds>]
-max chat
-```
-
-Opens an interactive readline session for back-and-forth conversation with Max.
-
-| REPL Command | Description                              |
-| ------------ | ---------------------------------------- |
-| `:help`      | Show available REPL commands             |
-| `:new`       | Start a new conversation on next message |
-| `:conv <id>` | Switch to a specific conversation ID     |
-| `:exit`      | Exit the REPL                            |
-| `Ctrl+C`     | Exit the REPL                            |
-
-**Example:**
-
-```bash
-# Start interactive chat
-max chat
-
-# Start with a specific profile
-max chat repl --profile work --debug
-```
-
-### Conversations (Public API)
-
-```bash
-max conversations list
-max conversations get <id>
-max conversations update <id> --data '{"key":"value"}'
-max conversations abort <id>
-# alias: max conv list
-```
-
-See `max conversations --help` for flags (`--profile`, `--base-url`, `--api-key`, `--debug`).
-
-## Conversation management
-
-- Max automatically remembers the last conversation ID in your profile. Subsequent messages continue that conversation.
-- Use `--new` to explicitly start a fresh conversation.
-- Use `--conversation <id>` to jump to a specific conversation.
-- In the REPL, use `:new` and `:conv <id>` to manage conversations interactively.
-
-## Troubleshooting
-
-- **"No Max API key found"**: run `max auth login <api-key>` or `frontline auth login <api-key>` on the same profile.
-- **"Message cannot be empty"**: provide a non-empty message string.
-- **Timeout waiting for reply**: increase `--timeout` or use `--no-wait` and check the conversation later.
-- Use `--debug` to see the full HTTP request URL, headers, and response status for diagnosing issues.
-- Use `--json` for machine-readable output that can be piped to `jq` or other tools.
+---
+name: max-chat
+description: Send messages to the Max AI assistant and manage conversations from the terminal. Use when the user wants to chat with Max, send a quick question, start a new conversation, or open an interactive chat session.
+---
+
+## Prerequisites
+
+- The `max` CLI must be installed (`npm i -g @frontline/cli` — provides both `frontline` and `max` binaries).
+- The user must have a per-user API key saved: `max auth login <api-key>` (or `frontline auth login` on the same profile).
+
+## Commands
+
+### Quick message (shorthand)
+
+```bash
+max "Your question here"
+max --new "Start a fresh conversation"
+```
+
+This is the fastest way to send a single message to Max. It uses the last active conversation by default, or `--new` to start a fresh one.
+
+Calls the **Public API**: `POST /public/v1/max/conversations/message` (Bearer = user API key). Responses use `{ "ok": boolean, "data": ... }`. Default stdout is **one-line JSON**; no spinner lines.
+
+| Flag                   | Description                                                 |
+| ---------------------- | ----------------------------------------------------------- |
+| `--new`                | Start a new conversation instead of continuing the last one |
+| `--conversation <id>`  | Send to a specific conversation ID                          |
+| `--no-wait`            | Do not poll for the assistant reply (fire and forget)       |
+| `--timeout <seconds>`  | Max seconds to wait for assistant reply (default: 60)       |
+| `--json`               | Print only the POST response JSON (no poll)                 |
+| `--pretty`             | Print assistant plain text from `data` instead of JSON      |
+| `--profile <name>`     | Use a specific Max CLI profile                              |
+| `--base-url <url>`     | Override Public API root (…/public/v1) for this run         |
+| `--api-base-url <url>` | Deprecated alias for `--base-url`                           |
+| `--api-key <key>`      | Override per-user API key for this run                      |
+| `--debug`              | Show HTTP request/response diagnostics                      |
+
+**Example:**
+
+```bash
+# Quick question using last conversation
+max "What agents do I have?"
+
+# Start a new conversation
+max --new "Help me set up a new workflow"
+
+# Send to a specific conversation
+max --conversation 123 "Continue from here"
+```
+
+### Send a message (explicit command)
+
+```bash
+max chat send <message...> [--new] [--conversation <id>] [--json] [--debug]
+```
+
+Same as the shorthand above but under the `chat send` subcommand. Default stdout is **one-line JSON**; **`--pretty`** for assistant plain text from `data`.
+
+### Interactive chat (REPL)
+
+```bash
+max chat repl [--profile <name>] [--debug] [--timeout <seconds>]
+max chat
+```
+
+Opens an interactive readline session for back-and-forth conversation with Max.
+
+| REPL Command | Description                              |
+| ------------ | ---------------------------------------- |
+| `:help`      | Show available REPL commands             |
+| `:new`       | Start a new conversation on next message |
+| `:conv <id>` | Switch to a specific conversation ID     |
+| `:exit`      | Exit the REPL                            |
+| `Ctrl+C`     | Exit the REPL                            |
+
+**Example:**
+
+```bash
+# Start interactive chat
+max chat
+
+# Start with a specific profile
+max chat repl --profile work --debug
+```
+
+### Conversations (Public API)
+
+```bash
+max conversations list
+max conversations get <id>
+max conversations update <id> --data '{"key":"value"}'
+max conversations abort <id>
+# alias: max conv list
+```
+
+See `max conversations --help` for flags (`--profile`, `--base-url`, `--api-key`, `--debug`).
+
+## Conversation management
+
+- Max automatically remembers the last conversation ID in your profile. Subsequent messages continue that conversation.
+- Use `--new` to explicitly start a fresh conversation.
+- Use `--conversation <id>` to jump to a specific conversation.
+- In the REPL, use `:new` and `:conv <id>` to manage conversations interactively.
+
+## Troubleshooting
+
+- **"No Max API key found"**: run `max auth login <api-key>` or `frontline auth login <api-key>` on the same profile.
+- **"Message cannot be empty"**: provide a non-empty message string.
+- **Timeout waiting for reply**: increase `--timeout` or use `--no-wait` and check the conversation later.
+- Use `--debug` to see the full HTTP request URL, headers, and response status for diagnosing issues.
+- Use `--json` for machine-readable output that can be piped to `jq` or other tools.

package/dist/skills/notes-and-tasks/SKILL.md

@@ -111,18 +111,18 @@ frontline object task delete <object> <task-id>
 
 ```bash
 # 1. Find the row you want to annotate
-frontline object record list sor__deals --search "Acme"
+frontline object record list standard__deals --search "Acme"
 # → row ID = 6625abc123def456
 
 # 2. Add a note
-frontline object note create sor__deals 6625abc123def456 \
+frontline object note create standard__deals 6625abc123def456 \
   --content "Discussed pricing on call"
 
 # 3. Add a follow-up task with a due date
-frontline object task create sor__deals 6625abc123def456 \
+frontline object task create standard__deals 6625abc123def456 \
   --content "Send revised proposal" \
   --due-date 2026-05-15
 
 # 4. Later, mark it complete
-frontline object task complete sor__deals 7
+frontline object task complete standard__deals 7
 ```