caraer-cli 0.1.2__tar.gz → 0.1.4__tar.gz

caraer_cli-0.1.4/AGENTS.md

@@ -0,0 +1,15 @@
+# Agent instructions
+
+## Agent skills
+
+### Issue tracker
+
+Issues and specs live in this repo's GitHub Issues (via `gh`). See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default triage roles mapped 1:1 (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

caraer_cli-0.1.4/CHANGELOG.md

@@ -0,0 +1,209 @@
+# Changelog
+
+## 0.1.4
+
+- HTTP webhooks are first-class on 2026.2.1: one YAML file each under
+  `src/app/webhooks/`. `caraer apps add webhook --mode HTTP --url …` writes
+  that file. Serverless webhooks stay on the function manifest.
+
+- Module `fields` is a list of field objects or `{ group: "Style", fields:
+  [...] }` expandables. Do not set `group` on a field. `advanced: true`
+  stays the unnamed Advanced settings group.
+
+- Clicking a `data-caraer-field` node in the CMS preview focuses that
+  sidebar field (local `caraer apps local` harness and the Flutter builder).
+  `examples/layout-v21` and new `caraer apps add module` scaffolds mark heading
+  and body.
+
+- `caraer apps push` warns when the workspace is still 2026.2 and offers to
+  rewrite it to 2026.2.1 (default yes). `--upgrade` / `--no-upgrade` skip the
+  prompt. `caraer apps upgrade` still rewrites without deploying.
+
+- Docs and `examples/layout-v21` match the 2026.2.1 layout: flat functions,
+  `src/app/appbars/`, JS lifecycle / inbound / schedules, webhook `label` and
+  `webhookFormat`, company-copy topics on the Webhooks tab, CMS Modules tab,
+  and `caraer apps delete` versus uninstall. `caraer apps add webhook`,
+  `add schedule`, and `add inbound` write 2026.2.1 code files (function
+  manifest / JS). JSON remains only on a 2026.2 workspace.
+
+- Webhook topics and required scopes read a key on a setting. A property
+  single-select uses `objectName` and `propertyName`
+  (`record.<setting:due_date.objectName>.date_due.<setting:due_date.propertyName>`,
+  and `records.<setting:due_date.objectName>.property.<setting:due_date.propertyName>.all`).
+  A mapping row is addressed by `fieldName` (`<setting:field_map.email>`).
+  Mapping scopes stay on the object. Caraer stores the concrete topic on the
+  company webhook when the app is installed or settings are saved.
+
+- Example app `examples/layout-v21`: full 2026.2.1 layout with settings,
+  inbound, schedule, app bar, CMS module, and a setting-targeted record webhook.
+
+- Guides for serverless functions, CMS modules, webhooks, lifecycle hooks,
+  schedules, and inbound routes: `docs/functions.md`, `docs/modules.md`,
+  `docs/webhooks.md`, `docs/app_lifecycle.md`, `docs/schedules.md`,
+  `docs/inbound.md`.
+
+- The default profile is `prod` (`https://api.caraer.com`). Built-in profiles
+  are `local` (`http://localhost:8080`), `dev` (`https://v2.dev.api.caraer.com`),
+  `staging` (`https://v2.staging.api.caraer.com`), and `prod`. Existing configs
+  that still use the old hosts are updated on the next command. Staging and
+  dev are not proxied through Cloudflare.
+
+- CMS preview reinstalls when `@caraer/cms-runtime` or `@caraer/cms-tokens`
+  are missing or are broken `caraer-web/packages` links, instead of treating
+  an existing `@astrojs/node` as enough.
+
+- CMS module preview (`.harness__preview`) uses block flow like live
+  `#main`, so section modules fill the frame instead of shrink-wrapping
+  in a centered flex row.
+
+- CMS module manifests can import shared field objects (for example
+  `widthField` from `src/app/modules/settings.ts`) instead of repeating
+  options in every module. Field groups can be spread (`...backgroundFields`).
+  Shared files at the modules root, and `_`-prefixed folders, are included
+  in the published package. Nested settings files may reuse exported arrays
+  such as `COLORS`.
+
+- `caraer apps push` is the one command for private and public apps: it
+  deploys by default, publishes CMS modules, and installs on the selected
+  company. `--no-deploy` syncs without a build. `--wait` blocks on function
+  runtime provisioning; the default skips that wait.
+
+- App `package.json` `dev` is `caraer apps local dev`, so `npm run dev` /
+  `pnpm dev` starts functions and the CMS preview. A missing `dev` script
+  is filled in; an existing one is left alone.
+
+- `apps local dev --cms` isolates the preview harness from the app
+  `package.json`, so pnpm does not skip `@astrojs/node`.
+
+- `apps init` scaffolds `src/app/modules/hello_world` (entry + `fields.d.ts`),
+  the same starter CMS module `apps add module` would create.
+
+- `apps init` writes a root `tsconfig.json` (same options as `caraer-core`) so
+  module scripts can resolve npm libraries from `package.json`. Node
+  `package.json` scaffolds set `"type": "module"`, `@caraer/client`, and the
+  published CMS contract packages (`@caraer/cms-runtime`, `@caraer/cms-tokens`)
+  and runs `npm install` so the default `hello_world` module resolves. They no
+  longer add `three` / `@types/three`. Add those only when a module imports
+  them.
+
+- Settings schema `filterPropertyTypes` / `filterPropertyFormats` on
+  `PROPERTY_SINGLE_SELECT` / `PROPERTY_MULTI_SELECT` (CMS alias
+  `allowedPropertyTypes` / `allowedPropertyFormats`)
+
+## 0.1.3
+
+- Settings schema `filterTraits` on `OBJECT_SINGLE_SELECT` / `OBJECT_MULTI_SELECT`
+  so installers can be limited to objects that have specific traits
+- Parse CMS module `manifest` object literals without `json5`, so existing
+  `caraer` installs keep working after this release
+
+- Settings schema `ACTION` fields with `actionSource` trigger a serverless
+  function without saving settings (cannot be `required` or a `visibleWhen` target)
+- App scaffolds write a public `# yaml-language-server: $schema=…` line that
+  loads [Caraer-HQ/caraer-app-schemas](https://github.com/Caraer-HQ/caraer-app-schemas)
+- Removed `caraer apps migrate-v2`. Existing V1 apps are migrated via the backend
+  Neo4j migration `apps-platform-v2` (`run-migration apps-platform-v2 up`).
+- Removed `caraer apps typegen`. Import serverless payload helpers from the
+  Caraer clients instead: `@caraer/client` (Node) / `caraer-client` (Python).
+  Node scaffolds add `@caraer/client` as a `devDependency`.
+- App scaffolds (`apps init` / wizard) default `hideApiKeyField: true` so the
+  installation API key is hidden in the Caraer UI unless explicitly shown
+- `caraer apps add schedule` interactive wizard: cron presets (hourly,
+  daily, weekdays, …) or custom Spring 5–6 field expression, plus
+  function picker, description, and enabled. `--cron` / `--description` /
+  `--enabled|--disabled` still work non-interactively.
+- **Breaking (with aliases):** regrouped `caraer apps` into nested
+  `add/`, `local/`, and `release/` groups. Golden-path leaves stay flat
+  (`list`, `select`, `init`, `push`, `validate`, …). Old flat paths
+  (`add-function`, `dev`, `deploy`, `builds`, …) remain as **hidden**
+  aliases that print a one-line deprecation warning. Aliases will be
+  removed after one release — migrate to the new paths now.
+- V2 runtimes now deploy straight from the pushed build archive (Cloud Run
+  style): the platform stores function metadata only, not source code. After a
+  build push, the CLI refreshes function UUID tracking read-only instead of
+  re-uploading code through the legacy API, and `apps pull` never overwrites
+  local sources when the platform has no stored code
+- Shared code: `src/app/shared/` is deployed at the runtime archive root, so
+  functions import helpers with the same relative path locally and deployed
+  (`require("../../shared")` from `functions/<name>/index.js`). No more
+  copying `shared.js` into every function folder (requires backend support;
+  platform 2026.2 build pushes only — legacy sync warns and skips it)
+- `function.caraer.json` is now optional: a folder under `src/app/functions/`
+  with `index.js` / `main.py` is a function named after the folder, using the
+  app-level runtime. Keep the manifest only for a custom `entry` or
+  `description`. Scaffolds and `apps pull` no longer write redundant manifests
+- `apps init` scaffolds a root `package.json` with npm scripts
+  (`dev`, `validate`, `push`, `deploy`, `logs`) for Node projects
+- `apps init` no longer creates empty `settings/`, `pricing/`, and `app-bars/`
+  directories; their writers create them on demand
+
+## 0.1.2
+
+- Cursor Agent Skill `caraer-apps` under `skills/caraer-apps`, installable via
+  `caraer skill install` / `caraer skill install --project`
+- JSON Schemas under `schemas/` for app / function / webhook / schedule /
+  inbound / lifecycle configs (IDE `$schema` + optional `caraer-cli[schemas]`)
+- `caraer apps typegen` writes `src/types/caraer.d.ts` (Node) or
+  `caraer_types.py` (Python) payload helpers
+- Example app `examples/webhook-inbox` (inbound catch → installation state)
+- Modular marketplace files: `src/app/settings/`, `pricing/`, `app-bars/`, `lifecycle/`
+  (merged into the manifest on push; split on pull). Scaffolds:
+  `apps add-setting|add-pricing-plan|add-app-bar|add-lifecycle-hook`
+- `apps validate` covers settings, pricing, app bars, and lifecycle hooks
+- `apps add-setting|pricing-plan|app-bar` use wizard prompts and append to
+  `app.caraer.yaml` by default (`--modular` for separate JSON files)
+- `apps init` always scaffolds all four lifecycle hooks + `on-*` functions
+- Function sync includes sidecar `sourceFiles` so multi-file handlers deploy correctly
+- Docs: [docs/app_lifecycle.md](docs/app_lifecycle.md); webhook-inbox includes all
+  lifecycle hooks (install/uninstall/rotate/update)
+- V2 local `apps dev` matches container contract: `POST /functions/{name}`,
+  `X-Caraer-Function` header, and `body.functionName` (legacy `POST /{name}` kept)
+- `apps dev` emulates installation state/secrets/jobs/connections + inbound routes;
+  `--invoke-schedule` fires a local schedule once
+- `apps deploy --wait/--no-wait` polls `runtimeStatus` (same as `push --deploy`)
+- `apps pull` aligns local `platformVersion`/`runtime` with remote and pulls
+  external OAuth providers
+- Installation commands: `apps state|secrets|jobs|connections`
+- `apps test` remote-invokes a function (or `--sample-only`); `apps rollback`
+  redeploys a prior READY build; `apps builds list|get`
+- `apps logs --all` fetches app-level V2 container logs
+- `apps validate` covers schedules, inbound routes, and OAuth providers
+- `apps push` / `pull` sync schedules, inbound routes, and OAuth providers
+  (in addition to manifest, functions, webhooks)
+- Local app definition is now **`src/app/app.caraer.yaml`** (legacy `app.caraer.json` still loads);
+  scaffolds include commented examples for scopes, settings, pricing, and app bars
+- App platform **V2** (`platformVersion: 2026.2`): one async container runtime per app;
+  `apps push --deploy` polls `runtimeStatus`; `apps status` shows runtime fields
+- Default scaffold is `2026.2`; use `--platform 2026.1` for legacy per-function Cloud Functions
+- Collapsed local **project** into **app**: `caraer.json` replaces `caraer.project.json`;
+  opaque developer-project id lives in `.caraer/state.json`
+- Single sync pair: `caraer apps pull` / `caraer apps push` syncs manifest, functions,
+  webhooks, schedules, inbound, and OAuth providers
+- Removed top-level `webhooks`, `pricing`, `appbars`, and `functions` command groups
+  (edit files under `src/app/` instead)
+- Removed `caraer apps link` and `caraer apps watch` (use `select` / `push` instead)
+- Removed deprecated `caraer project` command group (use `caraer apps` instead)
+- Removed `caraer config` command group (use `caraer profile` instead)
+- Removed `caraer completion` command group; shell completion is installed by `scripts/install.sh`
+- Public packaging polish: LICENSE, SECURITY, CONTRIBUTING; example defaults to `2026.2`
+- Developer sandboxes clone the selected company Neo4j DB only (same company
+  identity; `X-Caraer-Sandbox-Uuid` overrides `databaseid`). Recreate sandboxes
+  after upgrading past the old clone-company model
+  (`caraer sandbox use` / `clear`)
+- `caraer apps add-function` / `add-webhook` / `add-schedule` / `add-inbound`
+  scaffold local function folders and integration-runtime JSON files
+- Missing required args/options prompt interactively (questionary) instead of
+  failing with Typer usage errors; non-TTY still fails clearly
+- `caraer apps logs` prints log lines below the summary table; `--follow`
+  streams only new entries; skips unreadable Cloud Audit protobuf dumps
+
+## 0.1.0
+
+- Standalone `caraer-cli` package extracted from backend `clients/python`
+- Existing app / webhook / function commands
+- `caraer project` local project workflow (`init`, `link`, `upload`, `pull`, `watch`, `status`)
+- Build/deploy/logs/dev commands wired to developer-project APIs
+- `caraer functions delete`
+- `caraer sandbox` commands
+- Example project under `examples/webhook-inbox`
+- CI workflow and `scripts/ci.sh`

caraer_cli-0.1.4/PKG-INFO

@@ -0,0 +1,400 @@
+Metadata-Version: 2.5
+Name: caraer-cli
+Version: 0.1.4
+Summary: Developer CLI for Caraer apps, webhooks, and serverless functions.
+Project-URL: Homepage, https://caraer.com
+Project-URL: Documentation, https://developer.caraer.com
+Author: Caraer
+License: Proprietary
+License-File: LICENSE
+Keywords: apps,caraer,cli,marketplace,serverless
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.2.1
+Requires-Dist: platformdirs>=4.2.2
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: questionary>=2.0.1
+Requires-Dist: rich>=13.7.1
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12.3
+Provides-Extra: dev
+Requires-Dist: build>=1.2.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.2; extra == 'dev'
+Provides-Extra: schemas
+Requires-Dist: jsonschema>=4.22.0; extra == 'schemas'
+Description-Content-Type: text/markdown
+
+# Caraer CLI
+
+Developer CLI for building Caraer apps: serverless functions, webhooks, schedules,
+inbound routes, lifecycle hooks, and CMS modules.
+
+The CLI is a thin client of the Caraer API. You do not need GCP credentials on
+your machine.
+
+Docs: [developer.caraer.com](https://developer.caraer.com)
+
+## Requirements
+
+- **Python 3.10+** (the CLI itself)
+- **Node.js 22** and npm (default `nodejs22` runtime and the starter CMS module)
+- A Caraer account that can create apps in a company
+
+## Install
+
+```bash
+pipx install caraer-cli
+# or: uv tool install caraer-cli
+# or: pip install caraer-cli
+```
+
+Confirm:
+
+```bash
+caraer --version
+caraer profile current    # prod, https://api.caraer.com
+```
+
+A new install uses the `prod` profile. `caraer profile use local`, `dev`, or
+`staging` switches API host.
+
+### Install from source
+
+```bash
+git clone https://github.com/Caraer-HQ/caraer-cli.git
+cd caraer-cli
+python3 -m venv .venv
+source .venv/bin/activate
+./scripts/install.sh
+caraer --version
+```
+
+If install fails with `requires a different Python`, create the venv with
+`python3.10`, `python3.11`, or `python3.12`. Restart the terminal so tab
+completion loads.
+
+## Prompt for an AI coding agent
+
+Paste this into Cursor, Claude Code, or a similar agent. It installs the CLI,
+logs you into production, and scaffolds an app. It does not deploy.
+
+```text
+Set up the Caraer CLI on this machine and scaffold a Caraer app. Do not push,
+deploy, install, or publish the app unless I explicitly ask.
+
+1. Check Python is 3.10 or newer (`python3 --version`). If it is older, stop
+   and tell me how to install it.
+2. Check Node.js 22 is available (`node --version`). The default `nodejs22`
+   runtime and starter CMS module need it. If it is missing, stop and tell me.
+3. If `caraer --version` fails, install the CLI:
+   prefer `pipx install caraer-cli`, else `uv tool install caraer-cli`,
+   else `pip install caraer-cli`. Confirm with `caraer --version`.
+4. Confirm the active profile is production before login:
+   `caraer profile current`
+   base_url must be https://api.caraer.com. If it is not, run `caraer profile use prod`.
+5. Install the agent skills so later edits follow Caraer app conventions:
+   `caraer skill install`
+   Tell me to start a new chat before relying on those skills.
+6. Log in with `caraer auth login` and stop so I can approve the device code
+   in the browser. Do not ask for or type my password. If device login is
+   unavailable, ask me to run `caraer auth login --email <my-email>` myself.
+7. Run `caraer company list` and ask which company to use, then
+   `caraer company select <uuid>`.
+8. Ask whether the app is private to that company or a public marketplace app,
+   and what label to use. Then scaffold with platform 2026.2.1 (the default):
+   - Private: `caraer apps init --private --label "<Label>" --auth-method API_KEY`
+   - Public: `caraer apps init --label "<Label>"`
+   Do not pass `--platform 2026.1`.
+9. Change into the new folder and run `caraer apps validate`. Fix only errors
+   the scaffold itself reported.
+10. Summarize the folder, how to run it locally (`caraer apps local dev`), and
+    that `caraer apps push` deploys and installs on the selected company.
+    Wait for me before pushing.
+```
+
+After that chat, open a **new** agent chat in the app folder. The installed
+skills (`caraer-apps`, `caraer-cms`) are what teach the agent the app layout.
+
+```bash
+caraer skill install              # ~/.cursor/skills/caraer-apps and caraer-cms
+caraer skill install --project    # ./.cursor/skills in the current directory
+caraer skill list
+```
+
+## Quick start
+
+```bash
+caraer auth login
+# CI or password login: caraer auth login --email you@example.com
+caraer company list
+caraer company select <company-uuid>
+```
+
+Create a local app:
+
+```bash
+caraer apps init --label "My App"
+# company-only app:
+caraer apps init --private --label "Internal Tool" --auth-method API_KEY
+cd my_app
+caraer apps validate
+caraer apps local dev           # local server: POST /functions/<name>
+```
+
+Deploy only when you mean to. `caraer apps push` syncs the manifest, functions,
+webhooks, schedules, inbound routes, and OAuth providers, deploys the function
+build, publishes CMS modules, and installs the app on the selected company.
+
+```bash
+caraer apps push --dry-run
+caraer apps push                # add --wait to block until the runtime is READY
+caraer apps status
+caraer apps local logs          # the only local function, or a prompt
+caraer apps local logs --all
+```
+
+Only the company that created the app (or a super-admin) can push builds.
+
+`--no-deploy` syncs without a build. Private apps (`caraer apps init --private`,
+or `privateApp: true` in `caraer.json`) use the private app API and cannot be
+submitted with `caraer publish`.
+
+New apps use workspace `platformVersion: 2026.2.1` (one container per app). Use
+`--platform 2026.1` only for the legacy per-function model. See
+[docs/platform_versioning.md](docs/platform_versioning.md).
+
+### Add pieces
+
+Run these inside the app folder:
+
+```bash
+caraer apps add function my-action
+caraer apps add options-function list-items   # dynamic select options
+caraer apps add webhook --topic record.candidate.created --function my-action
+caraer apps add webhook --mode HTTP --topic record.candidate.updated --url https://example.com/hooks/caraer
+caraer apps add schedule heartbeat --cron "0 0 */12 * * *"
+caraer apps add inbound echo --auth NONE --sync
+caraer apps add setting
+caraer apps add lifecycle-hook
+caraer apps add module hello --kind section
+```
+
+On `2026.2.1` those write code files (see
+[`examples/layout-v21`](examples/layout-v21)):
+
+- Webhook: `exports.manifest.webhooks` on `src/app/functions/<name>.js`
+  (HTTP: `src/app/webhooks/<name>.yaml`)
+- Schedule: `src/app/schedules/<name>.js`
+- Inbound: `src/app/inbound/<name>.js`
+
+On `2026.2` `add webhook|schedule|inbound` still write JSON under
+`src/app/webhooks/`, `schedules/`, and `inbound/`.
+
+`caraer apps init` already creates lifecycle files
+(`src/app/lifecycle/{install,uninstall,rotate,update}.js`) and a starter
+`modules/hello_world`. A `2026.2` app is rewritten to `2026.2.1` on the
+next `caraer apps push` unless you decline the prompt (default yes) or
+pass `--no-upgrade`. `caraer apps upgrade` does the same rewrite without
+deploying. See [docs/platform_versioning.md](docs/platform_versioning.md).
+
+`add schedule` and `add setting` open a wizard when you omit flags.
+`add setting` writes into `src/app/settings.yaml`.
+
+## Project layout
+
+```text
+my_app/
+  caraer.json                 # platformVersion 2026.2.1, appUuid, privateApp
+  package.json
+  src/app/
+    app.caraer.yaml           # identity, scopes, auth, details
+    settings.yaml             # installer setting fields (optional section grouping)
+    functions/<name>.js       # name is the filename; serverless webhooks live in exports.manifest
+    appbars/<name>.js         # appBars on this file; Caraer runs it for app.bar.triggered
+    lifecycle/<hook>.js       # install | uninstall | rotate | update
+    schedules/<name>.js
+    inbound/<name>.js
+    webhooks/<name>.yaml      # HTTP webhooks (POST to a URL, no function)
+    shared/                   # require("../shared") from each of the above
+    modules/<name>/<name>.astro
+```
+
+A function is a file named after the function, with `exports.handler` (Node) or
+`def handler` (Python). Helpers live in `shared/`.
+
+Node handlers export `handler`. Payload types come from `@caraer/client`
+(`LifecyclePayload`, `WebhookPayload`, `SchedulePayload`):
+
+```js
+exports.handler = async (req, res) => {
+  const body = req.body || {};
+  res.status(200).json({ ok: true, event: body.event || null });
+};
+```
+
+Python handlers use `caraer-client` for the same payload types:
+
+```python
+def handler(request):
+    return {"statusCode": 200, "body": {"ok": True}}
+```
+
+Shared helpers live in `src/app/shared/` and are imported with the same relative
+path locally and when deployed, for example `require("../shared")` from
+`functions/<name>.js`.
+
+See [`examples/layout-v21`](examples/layout-v21) for a full `2026.2.1` app
+(named files, settings list, inbound, schedule, app bars, CMS module, and
+setting-targeted record and due-date webhooks).
+[`examples/webhook-inbox`](examples/webhook-inbox) is the older `2026.2`
+folder layout.
+
+A private app can be removed from the company that created it:
+
+```bash
+caraer apps delete            # selected private app; asks first
+caraer apps delete --yes      # no prompt
+```
+
+Uninstall is a different action: it removes one company's install and leaves
+the app in place. Delete is creator-company only, and only for private apps.
+
+## App pieces
+
+Each piece is a file under `src/app/` that points at a function, except CMS
+modules, which are Astro components published with the app.
+
+| Piece | What it does | Guide |
+|-------|----------------|-------|
+| Serverless functions | The code that runs | [docs/functions.md](docs/functions.md) |
+| CMS modules | Blocks for the website builder | [docs/modules.md](docs/modules.md) |
+| Webhooks | Run a function when a record or relation changes | [docs/webhooks.md](docs/webhooks.md) |
+| Lifecycle | Run a function on install, update, uninstall, or credential rotate | [docs/app_lifecycle.md](docs/app_lifecycle.md) |
+| Schedules | Run a function on a cron | [docs/schedules.md](docs/schedules.md) |
+| Inbound routes | Public HTTP from an outside system into a function | [docs/inbound.md](docs/inbound.md) |
+
+## Settings
+
+Installation settings are filled in by the admin who installs the app.
+
+`src/app/settings.yaml` is a single-level list of fields. Group related
+fields into installer cards with `section` / `sectionSubtitle` on the field.
+Caraer lays cards out left to right, top to bottom, at most 3 across.
+Fields without `section` stay schema-only (no section card).
+
+```yaml
+- name: candidate_mapping
+  type: MAPPING
+  label: Candidate mapping
+  section: Candidate
+  sectionSubtitle: Map CV fields and parsing behavior
+- name: parse_on_cv_change
+  type: SWITCH
+  label: Parse when a CV changes
+  section: Candidate
+- name: custom_mapping
+  label: Custom mapping for work experience
+  type: SWITCH
+  defaultValue: false
+- name: work_experience_mapping
+  type: MAPPING
+  visibleWhen:
+    - field: custom_mapping
+      operator: EQUALS
+      value: true
+```
+
+A field with `visibleWhen` is shown, required, and submitted only while every
+condition holds. Hidden fields are dropped.
+
+Operators: `EQUALS` (default), `NOT_EQUALS`, `IN`, `NOT_IN`, `IS_SET`,
+`IS_NOT_SET`.
+
+Do not ask the installer for the Caraer API base URL. The runtime injects
+`body.caraerApiBase`.
+
+`records.<setting:field>.all` on `requiredScopes` follows the installer's
+object pick. A path reads one key: `<setting:due_date.objectName>` and
+`<setting:due_date.propertyName>` for a property single-select, and
+`<setting:field_map.email>` for the mapping row whose `fieldName` is `email`.
+A property scope is
+`records.<setting:due_date.objectName>.property.<setting:due_date.propertyName>.all`.
+The same placeholders work on webhook topics. See
+[docs/webhooks.md](docs/webhooks.md).
+
+## Profiles
+
+Config is stored in the user config directory (`config.toml`). Built-in
+profiles:
+
+| Profile | API |
+|---------|-----|
+| `prod` (default) | `https://api.caraer.com` |
+| `staging` | `https://v2.staging.api.caraer.com` |
+| `dev` | `https://v2.dev.api.caraer.com` |
+| `local` | `http://localhost:8080` |
+
+`prod` is the Cloudflare edge. `staging` and `dev` are DNS aliases on Vercel
+(`v2.staging.api` → `staging.api.caraer.com`, `v2.dev.api` → `dev.api.caraer.com`)
+and are not proxied through Cloudflare.
+
+```bash
+caraer profile list
+caraer profile use staging
+caraer profile set --base-url https://api.caraer.com --output json
+```
+
+`--profile <name>` overrides the active profile for a single command.
+
+## Sandboxes
+
+A sandbox clones the selected company's Neo4j database. The company stays the
+same. Each company can have at most 3 active sandboxes.
+
+```bash
+caraer company select <company-uuid>
+caraer sandbox create --name my-test
+caraer sandbox use <sandbox-uuid>
+caraer sandbox clear
+```
+
+Sandboxes isolate Neo4j data. Function runtime code is still the deployed
+build. Preview a push with `caraer apps push --dry-run` before you deploy.
+
+## Command groups
+
+- `auth`, `company`, `profile` — session and which API you talk to
+- `apps` — scaffold, validate, push, logs, local dev, delete (private apps)
+- `webhooks` — formats, events, and test helpers
+- `publish` — marketplace review for public apps
+- `sandbox` — Neo4j clone of the selected company
+- `skill` — install the Cursor agent skills shipped with the CLI
+
+## Further reading
+
+- [Serverless functions](docs/functions.md)
+- [CMS modules](docs/modules.md)
+- [Webhooks](docs/webhooks.md)
+- [App lifecycle hooks](docs/app_lifecycle.md)
+- [Scheduled functions](docs/schedules.md)
+- [Inbound routes](docs/inbound.md)
+- [Platform versioning](docs/platform_versioning.md)
+- [Backend contract](docs/backend_contract.md)
+- [Changelog](CHANGELOG.md)
+- [Security](SECURITY.md)
+- Agent skills: [`skills/caraer-apps`](skills/caraer-apps), [`skills/caraer-cms`](skills/caraer-cms)
+
+## License
+
+Proprietary — see [LICENSE](LICENSE).