// Consolidated skill for building on the Insites platform. Use decision trees below to find the right component, then load detailed references.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | insites |
| description | Consolidated skill for building on the Insites platform. Use decision trees below to find the right component, then load detailed references. |
Follow these rules as written. Where they say "never" or "must", treat that literally ā those constraints exist to prevent specific real failures (Liquid syntax errors, security holes, audit failures). Conventions described in plain prose elsewhere in this document are guidance, not absolutes; use judgement.
After every file change, run the linter:
insites-cli audit
The audit must pass with zero errors before deployment. The hard requirements it enforces:
render 'path/name' resolves to app/views/partials/path/name.liquid{% graphql %} ā pages own data fetchingcontext.constantsThe decision trees below map common developer questions to the relevant reference doc. Walk through the matching tree before writing code so you load the right reference.
Need a page or endpoint?
āā HTML page with data ā pages/ + partials/ + graphql/
āā JSON API endpoint ā pages/ (with .json.liquid extension)
āā JavaScript endpoint ā pages/ (with .js.liquid extension)
āā Form submission handler ā pages/ (method: post) + forms/
āā File download/redirect ā pages/ + routing/
āā Admin-only page ā pages/ + authentication/ (page front-matter `authorization_policies:`)
āā Layout wrapper ā layouts/
āā Reusable UI component ā partials/
Need data operations?
āā Define a data model/table ā schema/
āā Query records (list/search/filter) ā graphql/ (records query)
āā Query single record by ID ā graphql/ (records query with id filter)
āā Create a record ā graphql/ (record_create mutation), called from forms/ callback_actions
āā Update a record ā graphql/ (record_update mutation), called from forms/ callback_actions
āā Delete a record ā graphql/ (record_delete mutation), called from forms/ callback_actions
āā Related records (belongs-to/has-many) ā graphql/ (related_record/related_records)
āā Paginate results ā graphql/ (page/per_page args)
āā Upload files ā schema/ (upload type) + forms/
āā Seed/migrate data ā migrations/
āā Bulk import/export ā migrations/ or insites-cli data commands
āā Access existing Postgres/ES/Redis ā graphql/ (all DB access via GraphQL only)
āā Contacts / companies / tasks / activities ā modules/crm/ (V2 REST API; see "I need CRM data" tree below)
Need CRM operations?
āā Start here (overview, audience routing) ā modules/crm/README.md
āā Look up V2 REST endpoints, conventions, errors ā modules/crm/api.md
āā Look up field-by-field schema (types, required, IIA columns) ā modules/crm/schema.md
āā Worked HTTP examples for common flows ā modules/crm/patterns.md
āā API edges and quirks (no Bearer prefix, etc.) ā modules/crm/gotchas.md
āā Configure custom fields / system fields / webhooks in IIA ā modules/crm/configuration.md
āā Override email layouts, hook into webhooks ā modules/crm/advanced.md
ā
āā Contacts (CRUD + addresses + personal info + profiles + relationships) ā modules/crm/api.md (Contacts)
āā Companies (CRUD + addresses + info + relationships + assign-contacts) ā modules/crm/api.md (Companies)
āā Custom fields (definitions in IIA, values via API) ā modules/crm/configuration.md + api.md (Custom fields)
āā System fields (contact type, lead source, industry, etc.) ā modules/crm/api.md (System fields) + configuration.md
ā
āā Tasks (CRUD + complete/open lifecycle) + task comments ā modules/crm/globals/tasks.md
āā Activities (calls, meetings, notes ā attached to a feature) ā modules/crm/globals/activities.md
āā File attachments (two-step S3 direct-upload flow) ā modules/crm/globals/attachments.md
āā Event streams (audit / activity feed, append-only) ā modules/crm/globals/event_streams.md
ā
āā Auth (instance API key, no Bearer prefix) ā references/api/authentication.md
āā Pipelines / stages / opportunities / cases ā NOT in v2 API (legacy v1 archived)
Need CMS operations?
āā Start here (overview, file-based stance) ā modules/cms/README.md
āā Look up object-type field shapes / front-matter ā modules/cms/metadata.md
āā Liquid-side consumption examples ā modules/cms/patterns.md
āā API edges / partial-alias quirks / overrides ā modules/cms/gotchas.md
āā IIA admin walkthrough per object type ā modules/cms/configuration.md
āā Override layouts/partials, hook_module_info ā modules/cms/advanced.md
ā
āā Pages (URL-addressable controllers) ā modules/cms/metadata.md (Pages)
āā Layouts (HTML scaffold wrappers) ā modules/cms/metadata.md (Layouts)
āā Partials (reusable HTML snippets, alias paths) ā modules/cms/metadata.md (Partials)
āā Web Files (static .js/.css/.html assets) ā modules/cms/metadata.md (Web Files)
āā Global Content (company-wide settings record) ā modules/cms/metadata.md (Global Content)
āā Collections (data-backed listing views) ā modules/cms/metadata.md (Collections)
āā Emails / SMS (templates) ā modules/cms/metadata.md (Emails/SMS)
āā Authorization Policies (page-gating rules) ā modules/cms/metadata.md (Authorization Policies)
Need data operations against user-defined databases?
āā Start here (overview, V2-first) ā modules/data/README.md
āā Look up V2 REST endpoints, conventions, item schema ā modules/data/api.md
āā Worked HTTP examples (CRUD, pagination, schema lookup) ā modules/data/patterns.md
āā API edges (URL prefix, PUT-not-PATCH, no UUIDs, etc.) ā modules/data/gotchas.md
āā Create / configure databases + columns in IIA ā modules/data/configuration.md
ā
āā Read database list / one database (read-only via API) ā modules/data/api.md (Databases)
āā CRUD database items ā modules/data/api.md (Database items)
āā Discover a database's column schema ā modules/data/patterns.md (#1)
āā Bulk import ā loop pattern (no native bulk endpoint) ā modules/data/patterns.md (#6)
ā
āā Auth (instance API key, no Bearer) ā references/api/authentication.md
āā Webhooks ā NONE on data module (audit-confirmed)
Need business logic?
āā Encapsulate a create/update/delete operation ā forms/ (callback_actions block)
āā Validate user input ā forms/ (YAML `validation:` blocks for fields; cross-field checks in callback_actions)
āā Run code asynchronously ā background-jobs/
āā Run code on a schedule ā background-jobs/ (with delay)
āā Send email after an action ā forms/ (callback_actions invoke email partial) + emails-sms/
Need auth?
āā Get current user ā authentication/ (context.current_user + GraphQL)
āā Check if user can do something ā authentication/ (authorization_policies + inline guard patterns)
āā Block unauthorized access (403) ā authentication/ (page front-matter `authorization_policies:`)
āā Redirect if not permitted ā authentication/ (inline unless/redirect_to, or a policy's own `redirect_to`)
āā Sign in a user ā authentication/ (sign_in tag)
āā Define a custom authorization policy ā authentication/ (file at `app/authorization_policies/<name>.liquid` referenced from page front matter)
āā OAuth2/social login ā authentication/
āā CSRF protection ā forms/ (authenticity_token)
āā Spam protection (reCAPTCHA/hCaptcha) ā forms/ (spam_protection tag)
Need Liquid help?
āā Insites-specific tags ā liquid/tags/
ā āā Execute GraphQL ā graphql tag
ā āā Call partial as function ā function tag
ā āā Render a partial ā render tag
ā āā Parse JSON data ā parse_json tag
ā āā Redirect user ā redirect_to tag
ā āā Set session data ā session tag
ā āā Log for debugging ā log tag
ā āā Cache output ā cache tag
ā āā Run code in background ā background tag
ā āā Database transactions ā transaction tag
ā āā Error handling ā try/catch tag
ā āā Export variables ā export tag
ā āā Set response headers/status ā response_headers/response_status tags
ā āā Sign in user ā sign_in tag
ā āā Spam protection ā spam_protection tag
āā Filters (data transformation) ā liquid/filters/
ā āā Array operations ā array_* filters
ā āā Hash/object operations ā hash_* filters
ā āā Date/time operations ā add_to_time, localize, strftime, to_time, etc.
ā āā String operations ā parameterize, slugify, titleize, humanize, etc.
ā āā JSON/encoding ā json, parse_json, base64_encode/decode, etc.
ā āā Validation ā is_email_valid, is_json_valid, matches, etc.
ā āā Currency/pricing ā pricify, pricify_cents, amount_to_fractional, etc.
ā āā Cryptography ā encrypt, decrypt, digest, compute_hmac, jwt_encode/decode
ā āā Translation ā t (translate), t_escape
ā āā Assets ā asset_url, asset_path
āā Objects (global data) ā liquid/objects/
ā āā context.params ā HTTP parameters
ā āā context.session ā session storage
ā āā context.location ā URL info
ā āā context.current_user ā user data
ā āā context.constants ā secrets/config
ā āā context.environment ā staging/production
ā āā context.exports ā exported partial variables
ā āā context.headers ā HTTP request headers
ā āā forloop/tablerowloop ā iteration helpers
āā Types ā liquid/types/
āā Variables (assign, capture, parse_json) ā liquid/variables/
āā Flow control (if/elsif/else/unless/case) ā liquid/flow-control/
āā Loops (for, cycle, tablerow) ā liquid/loops/
Need forms?
āā HTML form with CSRF ā forms/ (use <form> tag, NOT {% form %})
āā File upload ā forms/ (upload field type) + modules/cms/metadata.md (Web Files / Attachments)
āā Form validation ā forms/ (YAML `validation:` blocks; cross-field checks in callback_actions)
āā Display validation errors ā partials/ (render errors from form result)
āā Multi-step form ā pages/ + sessions/
āā AJAX form submission ā forms/ + pages/ (.json.liquid endpoint)
āā Spam protection ā forms/ (spam_protection tag)
Need notifications?
āā Send email ā emails-sms/ (email templates)
āā Send SMS ā emails-sms/ (SMS templates)
āā Flash messages/toasts ā flash-messages/
āā Send async (after action) ā background-jobs/ + emails-sms/
āā Email layout/styling ā layouts/ (mailer layout)
Need UI/styling?
āā View available styled components ā /style-guide on your instance
āā Layout structure ā layouts/
āā Reusable UI snippets ā partials/
āā Static assets (images, fonts, JS) ā assets/
Need integrations?
āā Call external REST API ā api-calls/
āā OAuth2 providers ā authentication/ (OAuth2 flow with sign_in tag)
āā Webhook receiver ā pages/ (POST endpoint)
āā Store API keys/secrets ā constants/
Need deployment?
āā Deploy to environment ā deployment/ (insites-cli deploy)
āā Watch logs ā cli/ (insites-cli logsv2)
āā Run Liquid/GraphQL ad-hoc ā cli/ (insites-cli exec)
āā Pull a module's code from an instance ā cli/ (insites-cli modules pull)
āā Set environment constants ā constants/ (insites-cli constants set)
āā Run migrations ā migrations/
āā Lint/validate code ā cli/ (insites-cli audit)
āā Sync files in development ā cli/ (insites-cli sync)
āā Environment configuration ā configuration/
Need performance?
āā Cache page fragments ā caching/ (cache tag)
āā Run heavy work in background ā background-jobs/ (background tag)
āā Avoid N+1 queries ā graphql/ (related_record/related_records)
āā Optimize pagination ā graphql/ (per_page limits)
āā Static asset CDN ā assets/ (asset_url filter)
āā Frontend optimization ā assets/ (lazy loading, code splitting)
āā Database query optimization ā graphql/ (filters, sorting)
Use the decision trees above to identify which category applies, then load the matching reference below. Each reference directory contains: README.md, configuration.md, api.md, patterns.md, gotchas.md, advanced.md.
| Category | Reference |
|---|---|
| Pages | references/pages/ |
| Layouts | references/layouts/ |
| Partials | references/partials/ |
| Routing | references/routing/ |
| Category | Reference |
|---|---|
| Schema | references/schema/ |
| GraphQL | references/graphql/ |
| Migrations | references/migrations/ |
| Category | Reference |
|---|---|
Forms (state-changing logic via callback_actions) | references/forms/ |
| Background Jobs | references/background-jobs/ |
| Category | Reference |
|---|---|
| Tags | references/liquid/tags/ |
| Filters | references/liquid/filters/ |
| Objects | references/liquid/objects/ |
| Types | references/liquid/types/ |
| Variables | references/liquid/variables/ |
| Flow Control | references/liquid/flow-control/ |
| Loops | references/liquid/loops/ |
| Category | Reference |
|---|---|
| Authentication | references/authentication/ |
| Forms | references/forms/ |
| Category | Reference |
|---|---|
| Emails & SMS | references/emails-sms/ |
| Flash Messages | references/flash-messages/ |
| Category | Reference |
|---|---|
| CRM (insites_core) | references/modules/crm/ |
| CMS (insites_cms) | references/modules/cms/ |
| Data (insites_databases) | references/modules/data/ |
| Module Template | references/modules/template/ |
Copy
references/modules/template/to create documentation for new Insites modules. Each module gets its own directory with: README.md, api.md, configuration.md, patterns.md, gotchas.md, advanced.md.
| Category | Reference |
|---|---|
| Constants | references/constants/ |
| Configuration | references/configuration/ |
| Assets | references/assets/ |
| Sessions | references/sessions/ |
| Caching | references/caching/ |
| Category | Reference |
|---|---|
| API Calls (outbound HTTP) | references/api-calls/ |
| API Endpoints (inbound, JSON) | references/api-endpoints/ |
| CRM Controllers | references/crm-controllers/ |
| User Profile Types | references/user-profile-types/ |
| Payments (Stripe) | references/payments/ |
| Category | Reference |
|---|---|
| CLI | references/cli/ |
| Deployment | references/deployment/ |
Pages fetch data via {% graphql %} and delegate the bulk of rendering to partials via {% render %}. Small amounts of page-specific inline HTML are acceptable in practice (a wrapper element, a one-off heading, the body of a .json.liquid page) ā what's not acceptable is duplicating markup that other pages could reuse, or putting form/card/list markup inline. Rule of thumb: more than ~10 lines of HTML in a page ā extract a partial.
ā references/pages/, references/partials/
Pages call {% graphql %} and pass results to partials as render arguments. New code should not put {% graphql %} inside a partial. Caveat: existing addons (notably older addon-* repos) contain partials that call GraphQL directly ā treat that as legacy debt. When working inside one of those addons, follow the local convention until a refactor is in scope; for new code in app-portal / app-seedling-style repos, keep GraphQL in pages.
ā references/graphql/, references/partials/
callback_actionsCreate/update/delete operations are driven by forms. Each forms/<name>.liquid declares its YAML schema (fields, validation) and a Liquid callback_actions block that runs the GraphQL mutations and side effects when the form is submitted. There is no separate app/lib/commands/ directory in canonical Combinate.
ā references/forms/
Don't edit files under modules/ ā that tree is replaced wholesale on every module update, so changes are lost. Modules are preinstalled per instance and updated through the Insites console, not the CLI. To override module behavior, place a same-path file under your app/ tree; Insites resolves your file ahead of the module's.
ā references/modules/
When the same logic appears twice, extract it. Use {% function %} for partials that return data; use {% render %} for partials that produce HTML. Repeated access checks belong in a reusable authorization_policies file referenced from page front matter, not duplicated inline.
ā references/partials/
Statements within {% liquid %} blocks must stay on a single line each ā line-wrapping causes Liquid syntax errors. Variables in Insites are local to the partial; use the export tag to share them across renders.
ā references/liquid/
Insites projects organise code by module, not by a flat root layout. Every project has a top-level modules/ directory containing one or more module folders (e.g. modules/dashboard/, modules/website/). Each module follows the same internal structure under modules/<name>/public/.
project-root/
āāā app.yml # Project-level configuration
āāā modules/
ā āāā <module>/ # e.g. dashboard, website, portal
ā ā āāā public/
ā ā ā āāā views/
ā ā ā ā āāā pages/ # Routed Liquid pages
ā ā ā ā āāā layouts/ # Page wrappers (e.g. portal_default)
ā ā ā ā āāā partials/ # Reusable template snippets
ā ā ā āāā forms/ # Form definitions (YAML + Liquid callback_actions)
ā ā ā āāā graphql/ # Queries + mutations grouped by domain
ā ā ā āāā authorization_policies/
ā ā ā āāā api_calls/ # Third-party API integrations grouped by service
ā ā ā āāā schema/ # Database table definitions (YAML)
ā ā ā āāā user_profile_types/ # Custom user-profile schemas
ā ā ā āāā emails/ # Email templates
ā ā ā āāā migrations/ # Data seeding and schema migrations
ā ā ā āāā assets/ # Module-scoped JS/CSS/images
ā ā āāā test/ # Module-level test fixtures (if any)
ā āāā <another-module>/
āāā package.json # (optional) Node.js dependencies
Module-prefixed paths. Render, include, and graphql calls always start with the module name:
{% render 'modules/dashboard/path/to/partial' %}
{% include 'modules/dashboard/path/to/partial' %}
{% graphql x = 'modules/dashboard/account/get_user' %}
For the full canonical layout reference (per-directory purpose, naming conventions, examples), see references/project-structure.md.
app/lib/commands/ directory. State-changing logic lives inline in pages or in forms/<name>.liquid callback_actions blocks.app/lib/queries/ directory. GraphQL files live at modules/<module>/public/graphql/<domain>/<operation>.graphql and are called directly from pages or forms.portal_default, portal_form, dashboard_default.| Extension | Content-Type | URL |
|---|---|---|
*.liquid or *.html.liquid | text/html | /path |
*.json.liquid | application/json | /path.json |
*.js.liquid | application/javascript | /path.js |
| Method | Page File | GraphQL Operation |
|---|---|---|
| GET | index, show, new, edit | records (search/find) |
| POST | create | record_create |
| PUT | update | record_update |
| DELETE | delete | record_delete |
./modules/ (read-only){% liquid %} blocks (causes syntax errors){% form %} tag for HTML forms (use plain <form> with CSRF token)insites-cli audit./app/context.constants)