Settings & projects

Setting profiles, project lifecycle, and structured requirements proposals: create and switch projects, store settings, save module manifests, and run describe-review-confirm builds.

These tools live in the on-demand catalog rather than the default tool list, keeping the connected client's context small. Discover them with search_tools (e.g. search_tools(queries: ["settings"])) and run them with execute_tools — or call them directly if your client has already loaded them.


Save Setting

save_setting via execute_tools

Create or update a setting profile. Data is merged with existing values. Access via config('name.key') in code.

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    Setting profile name (e.g., "app", "vote", "features")

  • Name
    data
    Type
    object
    Required
    required
    Description

    Key-value pairs for the setting (e.g., { "salt": "secret", "enabled": true })


Get Setting

get_setting read-only via execute_tools

Get a setting profile by name. Returns key-value pairs accessible via config() in code.

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    Setting profile name (e.g., "app", "database", "mail", or custom names like "vote")


Delete Setting

delete_setting via execute_tools

Delete a setting profile from the tenant's settings table.

WARNING: This permanently removes the entire setting profile and all its values. This cannot be undone.

EXAMPLE: { "name": "vote" }

This removes the "vote" setting profile entirely.

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    Setting profile name to delete


Save Project Meta

save_project_meta via execute_tools

Set the ACTIVE project's App Store card metadata — its display name and description. These are what the Constellation store card renders, so set them whenever a project is built for (or headed to) the store. Owner-only. Does NOT publish the project (listing stays a manual review) and cannot touch is_public or card images.

Parameters

  • Name
    name
    Type
    string
    Description

    Project display name (e.g., "Semantic Search"). Shown as the card title.

  • Name
    description
    Type
    string
    Description

    Card blurb shown under the title. One or two selling sentences.


Save Module

save_module via execute_tools

Set a project module's name and/or description. Modules are the named groups files/routes are organised into (created via the 'module' param on create_file/create_route); the description documents what the module provides for anyone browsing or reusing it.

Parameters

  • Name
    module
    Type
    string
    Required
    required
    Description

    Module UUID or kebab-case name (e.g., "ai-chat").

  • Name
    name
    Type
    string
    Description

    New module name (kebab-cased server-side).

  • Name
    description
    Type
    string
    Description

    What this module provides.

  • Name
    packages
    Type
    object
    Description

    Composer dependencies this module targets, written into the exported app's composer.json for this project AND every project that references the module. Map of package name to constraint, e.g. {"spatie/laravel-permission": "^6.0"}.

  • Name
    configs
    Type
    object
    Description

    Vendor config files this module ships into the exported app, for this project AND every project that references the module. Map of path to literal file content, e.g. {"config/permission.php": "<?php return ['teams' => true];"}. Paths must be flat config/<name>.php. Studio never loads these; they only land in exports.


List Module Catalogue

list_module_catalogue read-only via execute_tools

A build-readiness snapshot of the whole Constellation module catalogue — every module the requirements engine can match, with the flags that decide whether a matched module can actually be ASSEMBLED today. Use it to audit the module library against anticipated demand before a build.

Each module reports:

  • resolver_capable — carries the build data (baseline/route_specs or a component anchor) the settings resolver needs; a module without this is not assemblable yet.
  • has_canonical — its canonical source project is wired, so its files can be referenced into a build.
  • tier — 'foundation' (builds on any plan, including the free Hobby plan) or 'pro' (builds on any paid plan). is_free is the stored tier flag (true = foundation). There are NO per-module charges — the tier only decides which plan is needed.
  • buildable_on_free_plan — a foundation resolver module with its canonical wired (resolver_capable AND has_canonical AND foundation). Pro modules build the same way on any paid plan.
  • requires — module keys this one depends on; options_count, projected_tokens for context.

The envelope totals (total, resolver_capable, buildable_on_free_plan) give the coverage picture at a glance.

This tool takes no parameters.


Get Module Manifest

get_module_manifest read-only via execute_tools

Read one catalogue module's full build manifest by module_key (find keys with list_module_catalogue). The detail list_module_catalogue summarises but does not return.

Returns, as applies to the module:

  • settings — the typed knobs the settings resolver applies (key, type, allowed values, default, description, dependencies). Map each user requirement to one setting, then apply via apply_module_settings. (Server-side modules, e.g. auth's registration / email_verification / login_throttle.)
  • component — a front-end component module's referenceable anchor: its canonical root + nodes (the addressable parts, e.g. input/label/wrapper), and facets (what you may configure per instance). Read these before place_component, then pass config keyed by node name.
  • routes — the module's route specs; baseline — its files/routes; requires / provides / consumes — the dependency + capability graph; is_free — the tier flag.

Parameters

  • Name
    module
    Type
    string
    Required
    required
    Description

    The module_key from list_module_catalogue (e.g. "auth", "input", "lemon-squeezy").


Set Module Build Identity

set_module_build via execute_tools

Mark a catalogued module resolver-capable by setting its build identity as DATA: the module_key (resolver slug) plus the non-derivable bits (requires / conflicts / is_free / dependency_checks). Baseline + route_specs are NOT given here — they are projected off the module's canonical project; this links the canonical by name and derives them for you, so the module is buildable in one call.

Use this to make a new canonical-backed module buildable WITHOUT a platform code change — the module's resolver identity lives as data on the catalogue row.

FLOW:

  1. Author/publish the module's canonical as a public, platform-owned project named exactly like the catalogue module.
  2. Run modules:sync (or the admin Sync) so a catalogue row is harvested under that name.
  3. Call this with the module name + a kebab-case module_key.

Platform-admin only. The module name must already exist in the catalogue (list_module_catalogue).

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    The catalogue module name, exactly as listed by list_module_catalogue (e.g. "Lemon Squeezy Billing").

  • Name
    module_key
    Type
    string
    Required
    required
    Description

    Kebab-case resolver slug the manifest/apply path uses (e.g. "lemon-squeezy"). Lowercase letters, digits and hyphens only.

  • Name
    requires
    Type
    array
    Description

    Module keys this module depends on, applied before it (e.g. ["auth"]).

  • Name
    conflicts
    Type
    array
    Description

    Module keys mutually exclusive with this one (e.g. ["auth"] for a replacement auth base).

  • Name
    is_free
    Type
    boolean
    Description

    Tier flag — true if this module is included at no extra charge.

  • Name
    dependency_checks
    Type
    object
    Description

    Optional pre-apply checks keyed by name, each {profile, required_keys[], instruction} — e.g. a mail profile that must exist before applying.


Create Project

create_project via execute_tools

Create a fresh, empty project for the user and make it their ACTIVE project. Use when starting work that belongs in its own project (e.g. a new Constellation module) instead of building inside the currently open one. The current project is untouched — the active pointer is simply repointed. Owner-only and requires a paid plan (or a debug environment). Scaffolds the same starters as the UI: owner permission, app/database settings, a "/" homepage route and the routes directory.

Parameters

  • Name
    name
    Type
    string
    Description

    Project display name (e.g., "Metrics Dashboard"). Defaults to "New project".


Set Active Project

set_active_project via execute_tools

Switch the user's ACTIVE project to another project they own or have been assigned to. All other tools operate on the active project, so use this to move between projects (e.g. back to a module project to rename or extend it). Fails with 403 for projects the user has no access to.

Parameters

  • Name
    uuid
    Type
    string
    Required
    required
    Description

    UUID of the target project.


Delete Project

delete_project via execute_tools

Permanently delete a project you OWN, by uuid — and everything it owns: its code graph (files, routes, methods, elements, settings), version control, module ownership/state, capabilities, access rows, and — if it is a module canonical — its catalogue rows (module_prices and their module_options). Use to clean up throwaway/test projects or to remove/replace a module canonical. Owner-only. Public projects (module canonicals) ARE deletable. The one safeguard is referential: if this project's code is referenced by OTHER projects, the call refuses so you don't orphan their references — pass force=true to delete anyway. If you delete your currently-active project it repoints you to another owned project automatically (refusing only if it is your last). Irreversible.

Parameters

  • Name
    uuid
    Type
    string
    Required
    required
    Description

    UUID of a project you own to delete.

  • Name
    force
    Type
    boolean
    Description

    Delete even when other projects reference this one's code (orphaning their reference edges). Default false.


Propose Requirements

propose_requirements via execute_tools

Turn a plain-language description of what the user wants into a STRUCTURED requirements proposal: the catalogue modules it needs, each with its setting values. Every module and setting carries provenance — 'requested' (the description asked), 'predicted' (inferred; check the reason), or 'default' (schema default) — and anything uncertain is flagged for review rather than asked as a question. Show the proposal to the user as a table (module, setting, value, provenance, highlight uncertain rows), collect their edits via update_proposal, then confirm_proposal builds exactly what they accepted. Work no module covers is listed under 'unmatched', never silently dropped.

Parameters

  • Name
    description
    Type
    string
    Required
    required
    Description

    What the user wants built, in plain language — their words, not a summary.


Update Proposal

update_proposal via execute_tools

Apply the user's review edits to a draft requirements proposal — structurally and deterministically, no AI call. Exclude or re-include modules (set_modules), add catalogue modules the AI missed (add_modules), and change setting values (set_settings; values are validated against the declared option schema and rejected if they don't fit). Edits are atomic: any error changes nothing. Edited values are marked provenance 'requested'. Returns the updated proposal for re-display.

Parameters

  • Name
    proposal
    Type
    string
    Required
    required
    Description

    The proposal uuid from propose_requirements.

  • Name
    set_modules
    Type
    array
    Description

    Include or exclude modules already in the proposal.

  • Name
    add_modules
    Type
    array
    Description

    Add catalogue modules the proposal is missing (settings start at their defaults).

  • Name
    set_settings
    Type
    array
    Description

    Change setting values on modules in the proposal.


Confirm Proposal

confirm_proposal via execute_tools

Confirm a reviewed requirements proposal. The build runs ONLY when two gates pass: (1) no existing build already matches the request — if one does, 'existing_build' names it and nothing is assembled; (2) the user's plan covers every included module — foundation modules build on any plan, but Pro (non-foundation) modules need a paid plan. On a free plan a proposal that includes Pro modules returns 'upgrade_required' (the Pro module names and an upgrade link) and nothing is built; every paid plan includes every module, so the build runs straight through. There is no quote and no per-module charge. When the gates pass, the included resolver-capable modules apply to the active project as ONE dependency-ordered batch (same engine as apply_module_settings): files referenced from the canonical modules, routes created with the accepted setting values, settings written, class contributions applied. Any validation or dependency error applies NOTHING and the proposal stays a draft (fix via update_proposal or the error's remediation, then confirm again). On a clean build the proposal freezes — what the user accepted is exactly what was built. Modules with no resolver support yet return under 'unresolvable'. Only call this after the user has explicitly accepted the displayed proposal.

Parameters

  • Name
    proposal
    Type
    string
    Required
    required
    Description

    The proposal uuid the user accepted.