@useatlas/create 0.0.1 → 0.0.3

package/templates/nextjs-standalone/data/demo-semantic/entities/people.yml

@@ -1,145 +1,132 @@
 name: People
-type: fact_table
+type: dimension_table
 table: people
-grain: one row per person record
-description: Auto-profiled schema for people (198 rows). Contains 8 columns, linked to companies.
+grain: one row per contact
+description: |
+  Contacts at customer companies. Each person has a department, seniority level,
+  job title, and start date. Linked to companies via company_id. Use for
+  stakeholder mapping, org analysis, and understanding who we're selling to
+  and supporting at each company.
+
 dimensions:
   - name: id
     sql: id
     type: number
-    description: Primary key
+    description: Primary key — unique contact identifier
     primary_key: true
-    unique_count: 198
-    sample_values:
-      - '1'
-      - '2'
-      - '3'
-      - '4'
-      - '5'
-      - '6'
-      - '7'
-      - '8'
+
   - name: name
     sql: name
     type: string
-    unique_count: 198
-    sample_values:
-      - Alex Brown
-      - Alex Chen
-      - Alex Garcia
-      - Alex Kim
-      - Alex Mueller
-      - Alex Patel
-      - Alex Silva
-      - Alex Smith
+    description: Full name of the contact
+
   - name: email
     sql: email
     type: string
-    unique_count: 198
-    sample_values:
-      - alex.brown@company32.com
-      - alex.chen@company12.com
-      - alex.garcia@company42.com
-      - alex.kim@company32.com
-      - alex.mueller@company2.com
-      - alex.patel@company22.com
-      - alex.silva@company22.com
-      - alex.smith@company1.com
+    description: Work email address
+
   - name: company_id
     sql: company_id
     type: number
-    description: Foreign key to companies
-    unique_count: 50
-    sample_values:
-      - '1'
-      - '2'
-      - '3'
-      - '4'
-      - '5'
-      - '6'
-      - '7'
-      - '8'
+    description: Foreign key to companies — which company this person works at
+
   - name: department
     sql: department
     type: string
-    unique_count: 6
-    sample_values:
-      - Engineering
-      - Finance
-      - Marketing
-      - Operations
-      - Product
-      - Sales
+    description: Functional department within the company
+    sample_values: [Engineering, Finance, Marketing, Operations, Product, Sales]
+
   - name: seniority
     sql: seniority
     type: string
-    unique_count: 4
-    sample_values:
-      - Executive
-      - Junior
-      - Mid
-      - Senior
+    description: Career level — indicates decision-making authority
+    sample_values: [Executive, Senior, Mid, Junior]
+
   - name: title
     sql: title
     type: string
-    unique_count: 30
-    sample_values:
-      - Accountant
-      - Account Executive
-      - Backend Engineer
-      - Brand Manager
-      - CFO
-      - Content Strategist
-      - Controller
-      - Data Analyst
+    description: Job title (e.g. CFO, Backend Engineer, Account Executive)
+
   - name: start_date
     sql: start_date
     type: date
-    unique_count: 158
-    sample_values:
-      - Wed Jan 10 2018 00:00:00 GMT-0500 (Eastern Standard Time)
-      - Mon Jan 15 2018 00:00:00 GMT-0500 (Eastern Standard Time)
-      - Thu Feb 01 2018 00:00:00 GMT-0500 (Eastern Standard Time)
-      - Sat Mar 10 2018 00:00:00 GMT-0500 (Eastern Standard Time)
-      - Tue Mar 20 2018 00:00:00 GMT-0400 (Eastern Daylight Time)
-      - Sun Apr 01 2018 00:00:00 GMT-0400 (Eastern Daylight Time)
-      - Sun Apr 15 2018 00:00:00 GMT-0400 (Eastern Daylight Time)
-      - Thu May 10 2018 00:00:00 GMT-0400 (Eastern Daylight Time)
+    description: Date the person started at their company
+
   - name: start_date_year
     sql: EXTRACT(YEAR FROM start_date)
     type: number
-    description: Year extracted from start_date
+    description: Year the person started — useful for tenure analysis
     virtual: true
-  - name: start_date_month
-    sql: TO_CHAR(start_date, 'YYYY-MM')
-    type: string
-    description: Year-month extracted from start_date
+
+  - name: tenure_years
+    sql: EXTRACT(YEAR FROM AGE(CURRENT_DATE, start_date))
+    type: number
+    description: Approximate years of tenure at the company
     virtual: true
+
 measures:
-  - name: person_count
+  - name: contact_count
     sql: id
     type: count_distinct
+    description: Number of unique contacts
+
+  - name: avg_tenure
+    sql: EXTRACT(YEAR FROM AGE(CURRENT_DATE, start_date))
+    type: avg
+    description: Average tenure in years
+
 joins:
   - target_entity: Companies
     relationship: many_to_one
     join_columns:
       from: company_id
       to: id
-    description: Each person belongs to one company
+    description: Each contact belongs to one company
+
 use_cases:
-  - Use for segmentation analysis by department, seniority
-  - Use for time-series analysis using start_date
-  - Join with companies for cross-entity analysis
+  - Stakeholder mapping — who are the key contacts at each company
+  - Department breakdown — what functions are represented
+  - Seniority analysis — how many executives vs individual contributors
+  - Hiring trends — when were contacts added, by year
+  - Join to companies + accounts for full customer intelligence
+
 query_patterns:
-  - description: People by department
+  - name: contacts_by_department
+    description: Contact count by department
     sql: |-
-      SELECT department, COUNT(*) as count
+      SELECT department,
+             COUNT(*) AS contact_count
       FROM people
       GROUP BY department
-      ORDER BY count DESC
-  - description: People by seniority
+      ORDER BY contact_count DESC
+
+  - name: contacts_by_seniority
+    description: Contact distribution by seniority level
     sql: |-
-      SELECT seniority, COUNT(*) as count
+      SELECT seniority,
+             COUNT(*) AS contact_count
       FROM people
       GROUP BY seniority
-      ORDER BY count DESC
+      ORDER BY contact_count DESC
+
+  - name: executives_by_company
+    description: Executive contacts per company
+    sql: |-
+      SELECT c.name AS company,
+             COUNT(*) AS executive_count
+      FROM people p
+      JOIN companies c ON p.company_id = c.id
+      WHERE p.seniority = 'Executive'
+      GROUP BY c.name
+      ORDER BY executive_count DESC
+
+  - name: contacts_per_company
+    description: Contact density per company
+    sql: |-
+      SELECT c.name AS company,
+             COUNT(*) AS contact_count,
+             c.employee_count AS total_employees
+      FROM people p
+      JOIN companies c ON p.company_id = c.id
+      GROUP BY c.name, c.employee_count
+      ORDER BY contact_count DESC

package/templates/nextjs-standalone/data/demo-semantic/glossary.yml

@@ -1,22 +1,118 @@
 terms:
+  MRR:
+    status: defined
+    definition: >
+      Monthly Recurring Revenue. The sum of monthly_value across all active accounts.
+      Use accounts.monthly_value and filter by status = 'Active' for current MRR.
+    tables:
+      - accounts
+
+  ARR:
+    status: defined
+    definition: >
+      Annual Recurring Revenue. MRR * 12. Not stored directly — calculate from
+      accounts.monthly_value.
+    tables:
+      - accounts
+
+  ARPA:
+    status: defined
+    definition: >
+      Average Revenue Per Account. Total MRR divided by active account count.
+      Use AVG(monthly_value) on active accounts.
+    tables:
+      - accounts
+
+  churn:
+    status: defined
+    definition: >
+      An account with status = 'Churned'. Churned accounts have monthly_value = 0
+      and typically have a contract_end date set.
+    tables:
+      - accounts
+
+  plan:
+    status: defined
+    definition: >
+      Subscription tier. Four levels: Free ($0), Starter (~$49-89/mo),
+      Pro (~$299-500/mo), Enterprise (~$5,000-15,000/mo).
+    tables:
+      - accounts
+
+  status:
+    status: ambiguous
+    note: >
+      "status" appears on accounts only, but could be confused with general
+      state. Always refers to subscription status: Active, Inactive,
+      Suspended, or Churned.
+    possible_mappings:
+      - accounts.status
+
   name:
     status: ambiguous
-    note: '"name" appears in multiple tables: companies, people. ASK the user which table they mean.'
+    note: >
+      "name" appears in both companies and people. ASK the user which
+      entity they mean — company name or person name.
     possible_mappings:
       - companies.name
       - people.name
+
   company:
     status: defined
-    definition: Refers to the companies entity. Linked via accounts.company_id → companies.id.
-  plan:
+    definition: >
+      Refers to the companies entity (our customers). Linked from accounts
+      and people via company_id -> companies.id.
+    tables:
+      - companies
+      - accounts
+      - people
+
+  industry:
     status: defined
-    definition: 'Categorical field on accounts. Possible values: Enterprise, Free, Pro, Starter.'
-  status:
+    definition: >
+      Business sector of a customer company. Values: Education, Energy,
+      Finance, Healthcare, Manufacturing, Media, Retail, Technology.
+    tables:
+      - companies
+
+  country:
     status: defined
-    definition: 'Categorical field on accounts. Possible values: Active, Churned, Inactive, Suspended.'
+    definition: >
+      ISO 2-letter country code for company HQ location. Values: AU, BR,
+      CA, DE, FR, IN, JP, SG, UK, US.
+    tables:
+      - companies
+
   department:
     status: defined
-    definition: 'Categorical field on people. Possible values: Engineering, Finance, Marketing, Operations, Product, Sales.'
+    definition: >
+      Functional department of a contact. Values: Engineering, Finance,
+      Marketing, Operations, Product, Sales.
+    tables:
+      - people
+
   seniority:
     status: defined
-    definition: 'Categorical field on people. Possible values: Executive, Junior, Mid, Senior.'
+    definition: >
+      Career level of a contact. Values: Executive, Senior, Mid, Junior.
+    tables:
+      - people
+
+  revenue:
+    status: ambiguous
+    note: >
+      Could mean company revenue (companies.revenue — annual total revenue
+      of the customer) or account revenue (accounts.monthly_value — our MRR
+      from that account). Clarify which is meant.
+    possible_mappings:
+      - companies.revenue
+      - accounts.monthly_value
+
+  contract:
+    status: defined
+    definition: >
+      Subscription agreement period. contract_start is when billing began;
+      contract_end is set when an account churns or is terminated.
+      NULL contract_end means the account is still under contract.
+    tables:
+      - accounts

package/templates/nextjs-standalone/data/demo-semantic/metrics/accounts.yml

@@ -1,38 +1,77 @@
 metrics:
-  - id: accounts_count
-    label: Total Accounts
-    description: Count of distinct accounts records.
-    type: atomic
-    sql: |-
-      SELECT COUNT(DISTINCT id) as count
-      FROM accounts
-    aggregation: count_distinct
-  - id: total_monthly_value
-    label: Total monthly value
-    description: Sum of monthly_value across all accounts.
+  - id: total_mrr
+    label: Total MRR
+    description: Total Monthly Recurring Revenue across all active accounts.
     type: atomic
+    unit: USD
     source:
       entity: Accounts
-      measure: total_monthly_value
+      measure: total_mrr
     sql: |-
-      SELECT SUM(monthly_value) as total_monthly_value
+      SELECT SUM(monthly_value) AS total_mrr
       FROM accounts
+      WHERE status = 'Active'
     aggregation: sum
     objective: maximize
-  - id: avg_monthly_value
-    label: Average monthly value
-    description: Average monthly_value per account.
+
+  - id: active_accounts
+    label: Active Accounts
+    description: Number of accounts with status = 'Active'.
     type: atomic
     sql: |-
-      SELECT AVG(monthly_value) as avg_monthly_value
+      SELECT COUNT(*) AS active_accounts
       FROM accounts
+      WHERE status = 'Active'
+    aggregation: count
+
+  - id: arpa
+    label: ARPA (Avg Revenue Per Account)
+    description: Average MRR per active account.
+    type: derived
+    unit: USD
+    sql: |-
+      SELECT AVG(monthly_value) AS arpa
+      FROM accounts
+      WHERE status = 'Active'
     aggregation: avg
-  - id: monthly_value_by_plan
-    label: monthly value by plan
-    description: monthly_value broken down by plan.
-    type: atomic
+
+  - id: churn_rate
+    label: Churn Rate
+    description: Percentage of all accounts that have churned.
+    type: derived
+    unit: percent
+    sql: |-
+      SELECT ROUND(100.0 * COUNT(*) FILTER (WHERE status = 'Churned') / COUNT(*), 1) AS churn_rate
+      FROM accounts
+    aggregation: ratio
+    objective: minimize
+
+  - id: mrr_by_plan
+    label: MRR by Plan
+    description: MRR breakdown by subscription plan tier.
+    type: breakdown
+    unit: USD
+    sql: |-
+      SELECT plan,
+             SUM(monthly_value) AS total_mrr,
+             COUNT(*) AS account_count,
+             AVG(monthly_value) AS avg_mrr
+      FROM accounts
+      WHERE status = 'Active'
+      GROUP BY plan
+      ORDER BY total_mrr DESC
+
+  - id: churn_by_plan
+    label: Churn Rate by Plan
+    description: Churn rate broken down by plan tier.
+    type: breakdown
+    unit: percent
     sql: |-
-      SELECT plan, SUM(monthly_value) as total_monthly_value, AVG(monthly_value) as avg_monthly_value, COUNT(*) as count
+      SELECT plan,
+             COUNT(*) FILTER (WHERE status = 'Churned') AS churned,
+             COUNT(*) AS total,
+             ROUND(100.0 * COUNT(*) FILTER (WHERE status = 'Churned') / COUNT(*), 1) AS churn_pct
       FROM accounts
       GROUP BY plan
-      ORDER BY total_monthly_value DESC
+      ORDER BY churn_pct DESC
+    objective: minimize

package/templates/nextjs-standalone/data/demo-semantic/metrics/companies.yml

@@ -1,89 +1,63 @@
 metrics:
-  - id: companies_count
-    label: Total Companies
-    description: Count of distinct companies records.
+  - id: total_customers
+    label: Total Customers
+    description: Number of unique customer companies.
     type: atomic
     sql: |-
-      SELECT COUNT(DISTINCT id) as count
+      SELECT COUNT(DISTINCT id) AS total_customers
       FROM companies
     aggregation: count_distinct
-  - id: total_employee_count
-    label: Total employee count
-    description: Sum of employee_count across all companies.
+
+  - id: avg_customer_revenue
+    label: Avg Customer Revenue
+    description: Average annual revenue across customer companies.
     type: atomic
+    unit: USD
     source:
       entity: Companies
-      measure: total_employee_count
+      measure: avg_revenue
     sql: |-
-      SELECT SUM(employee_count) as total_employee_count
-      FROM companies
-    aggregation: sum
-    objective: maximize
-  - id: avg_employee_count
-    label: Average employee count
-    description: Average employee_count per company.
-    type: atomic
-    sql: |-
-      SELECT AVG(employee_count) as avg_employee_count
-      FROM companies
-    aggregation: avg
-  - id: total_founded_year
-    label: Total founded year
-    description: Sum of founded_year across all companies.
-    type: atomic
-    source:
-      entity: Companies
-      measure: total_founded_year
-    sql: |-
-      SELECT SUM(founded_year) as total_founded_year
-      FROM companies
-    aggregation: sum
-    objective: maximize
-  - id: avg_founded_year
-    label: Average founded year
-    description: Average founded_year per company.
-    type: atomic
-    sql: |-
-      SELECT AVG(founded_year) as avg_founded_year
-      FROM companies
-    aggregation: avg
-  - id: total_revenue
-    label: Total revenue
-    description: Sum of revenue across all companies.
-    type: atomic
-    source:
-      entity: Companies
-      measure: total_revenue
-    sql: |-
-      SELECT SUM(revenue) as total_revenue
-      FROM companies
-    aggregation: sum
-    objective: maximize
-  - id: avg_revenue
-    label: Average revenue
-    description: Average revenue per company.
-    type: atomic
-    sql: |-
-      SELECT AVG(revenue) as avg_revenue
-      FROM companies
-    aggregation: avg
-  - id: total_valuation
-    label: Total valuation
-    description: Sum of valuation across all companies.
-    type: atomic
-    source:
-      entity: Companies
-      measure: total_valuation
-    sql: |-
-      SELECT SUM(valuation) as total_valuation
-      FROM companies
-    aggregation: sum
-    objective: maximize
-  - id: avg_valuation
-    label: Average valuation
-    description: Average valuation per company.
-    type: atomic
-    sql: |-
-      SELECT AVG(valuation) as avg_valuation
+      SELECT AVG(revenue) AS avg_customer_revenue
       FROM companies
     aggregation: avg
+
+  - id: customers_by_industry
+    label: Customers by Industry
+    description: Customer count and average revenue by industry vertical.
+    type: breakdown
+    sql: |-
+      SELECT industry,
+             COUNT(*) AS customer_count,
+             AVG(revenue) AS avg_revenue,
+             AVG(employee_count) AS avg_headcount
+      FROM companies
+      GROUP BY industry
+      ORDER BY customer_count DESC
+
+  - id: customers_by_country
+    label: Customers by Country
+    description: Customer distribution by HQ country.
+    type: breakdown
+    sql: |-
+      SELECT country,
+             COUNT(*) AS customer_count,
+             SUM(revenue) AS total_revenue
+      FROM companies
+      GROUP BY country
+      ORDER BY customer_count DESC
+
+  - id: revenue_per_customer
+    label: Revenue per Customer (our MRR)
+    description: Total MRR we earn from each customer company.
+    type: derived
+    unit: USD
+    sql: |-
+      SELECT c.name AS company,
+             c.industry,
+             SUM(a.monthly_value) AS total_mrr,
+             COUNT(a.id) AS account_count
+      FROM companies c
+      JOIN accounts a ON a.company_id = c.id
+      WHERE a.status = 'Active'
+      GROUP BY c.name, c.industry
+      ORDER BY total_mrr DESC

package/templates/nextjs-standalone/docs/deploy.md

@@ -4,7 +4,7 @@ Atlas provides two example deployment topologies plus a static landing page. Dep
 
 | Example | What's included | Use when |
 |---------|----------------|----------|
-| [`examples/docker/`](../examples/docker/) | Hono API + Docker + optional nsjail | Self-hosted deployment (Railway, Render, Docker Compose) |
+| [`examples/docker/`](../examples/docker/) | Hono API + Docker + optional nsjail | Self-hosted deployment (Railway, Docker Compose) |
 | [`examples/nextjs-standalone/`](../examples/nextjs-standalone/) | Next.js + embedded Hono API | You want to deploy to Vercel with zero infrastructure |
 | [`apps/www/`](../apps/www/) | Static landing page (Next.js export + Bun server) | Marketing site at useatlas.dev |
 
@@ -28,7 +28,7 @@ Go from zero to production with managed Postgres included.
 1. **Scaffold your project:**
 
 ```bash
-bun create atlas-agent my-app
+bun create @useatlas my-app
 cd my-app
 ```
 
@@ -134,7 +134,7 @@ Atlas runs agent-generated commands (filesystem exploration, future code executi
 |------|---------|-----------|-----------------|
 | 1 | Vercel Sandbox | Vercel | Firecracker microVM (hardware-level). No network, ephemeral filesystem |
 | 2 | nsjail | Self-hosted Docker/VM | Linux namespaces. No network, read-only mount, separate PID/user space |
-| 3 | Sidecar service | Railway, Render (planned) | Separate container with no secrets. Process-level isolation via private networking |
+| 3 | Sidecar service | Railway | Separate container with no secrets. Process-level isolation via private networking |
 | 4 | just-bash | Everywhere (fallback) | In-memory OverlayFS + path-traversal protection. No process isolation |
 
 ### What's right for you?
@@ -260,43 +260,6 @@ Railway exposes a public URL. Check health at `https://<your-app>.up.railway.app
 
 ---
 
-## Render
-
-Atlas includes a `render.yaml` Blueprint in `examples/docker/`.
-
-### Steps
-
-1. Go to the [Render Dashboard](https://dashboard.render.com/) and click **New > Blueprint**
-2. Connect your GitHub repo -- Render reads `examples/docker/render.yaml`
-3. Set the prompted environment variables:
-   - `ATLAS_DATASOURCE_URL` -- your analytics database connection string
-   - `ANTHROPIC_API_KEY` -- your API key
-4. Deploy
-
-### Using Render Postgres
-
-1. Create a Render Postgres instance from the dashboard
-2. Copy the **Internal Connection String**
-3. Set it as `DATABASE_URL` (Atlas internal) and create a separate database for `ATLAS_DATASOURCE_URL` (analytics)
-
-### Configuration
-
-The `examples/docker/render.yaml` configures:
-
-- Docker-based deployment using the example's Dockerfile
-- Health check at `/api/health`
-- Starter plan
-- `ATLAS_PROVIDER` defaults to `anthropic`
-- `autoDeploy` is disabled -- trigger deploys manually from the Render dashboard, or set `autoDeploy: true` in `render.yaml` to deploy on every push
-
-### Verify
-
-```bash
-curl https://<your-app>.onrender.com/api/health
-```
-
----
-
 ## Vercel
 
 Atlas provides a Next.js standalone example that embeds the Hono API via a catch-all route — deploy to Vercel with zero infrastructure. The explore tool automatically uses Vercel Sandbox (Firecracker VM isolation) when running on Vercel.
@@ -304,7 +267,7 @@ Atlas provides a Next.js standalone example that embeds the Hono API via a catch
 ### Scaffold a new project
 
 ```bash
-bun create atlas-agent my-app --platform vercel
+bun create @useatlas my-app --platform vercel
 cd my-app
 ```