Projects and source

Use Projects to give an application a stable home before you compile, add Sidecars or ask Agent to work on it. By the end of this guide, you will have a project, an explicitly selected application and the correct source folders linked to it.

A project groups related applications and their settings. An application component is one independently compilable application inside that project. A source root is a folder used by that application. A Sidecar adds a capability to an application; it is not another name for an application component.

Before you begin

Open the local cApp workspace or installed cApp, with its local service available. The public documentation and Showroom website do not have access to your computer's project folders. Keep your application source in a folder you control. A simple application can start with an index.html; a framework application needs its actual source and build configuration, not just a screenshot or a link to its website.

Linking source is not a backup. Keep the source and any release/signing material you need in your normal version-control or backup process. Layout exports describe locations; they do not contain the files at those locations.

Find your workspace

On Windows the default workspace is %USERPROFILE%\cApp. Projects shows the Workspace root reported by the connected service. Expand Workspace folders to inspect its locations, or use Open root where the host supports opening folders. The workspace holds project records, bundles, imported Sidecars and Agent state.

Source folders can live elsewhere. Linking a repository does not move it into this workspace. A browser connected to cApp's local service uses paths on that service's computer, not a remote visitor's computer.

If Your projects reports a connection error, use Refresh and read the error before creating another project. Installed cApp starts its own service bridge; restart the installed application after updating it. An unavailable service does not mean your folders have been deleted.

Create and reopen a project

1. Open Projects → Create project. Enter a recognisable Project name and a stable Project ID. The ID accepts letters, numbers, underscores, dots and hyphens; keep it stable rather than changing it for each release.
2. Set App version and the intended Target platforms. Windows and Android have different runtime requirements; selecting a target is not proof that every component supports it.
3. Optionally enter Initial source. This creates an All source root for the first application. Leave it empty to link source in Build later.
4. Enter a Hosted runtime backend only when your app needs an already deployed service. Do not put the local cApp build service or a private access token in this field.
5. Choose Create project, open its card under Your projects, and confirm the Active project heading before following Build → Source & package.

Reopen the same project for later edits and releases. Close leaves the project rather than deleting its source. Open folder opens the project workspace, which can be different from the linked application repository. Save persists the current project state; it does not compile or publish an application.

Link and organise source

In Build, choose Project folders and check App to build. Use + Folder to add source to that application, choose each folder's role, then Refresh app to inspect it. A one-off Repository ZIP upload is a different source mode, not a persistent link that tracks later edits to your repository.

Do not add several complete independent applications as roots of one compile target. Use + New app for each independent application, then select it before adding its folders. Rename changes its presentation; preserving the component ID keeps its release history attached. When cApp offers Organise folders into apps, review the proposed grouping rather than treating it as proof of your application's architecture.

For a multi-app project, Scan project inspects the components; Build product apps compiles the usable product surfaces; Build project also includes available diagnostic surfaces. These are project compilation controls, not a promise of one installer containing all applications. Inspect each result and package the intended component separately. Stop after current finishes the current component before stopping the batch.

Unlink all removes the selected application's source links. It does not erase the original directories. A source edit, changed folder role or changed component layout needs a new compile before it can appear in a release.

Move layout metadata between tools

Projects and Build expose Export layout, Download shell and Import JSON for capp.project-layout.v1. Download the shell for the currently open project, replace its example paths with real local paths, and keep its project ID aligned with the destination.

This minimal example describes one application; replace both the ID and path before importing:

{
  "protocol": "capp.project-layout.v1",
  "project": {"id": "hello-capp", "name": "Hello cApp"},
  "activeComponentId": "main",
  "components": [
    {
      "id": "main",
      "name": "Hello cApp",
      "kind": "application",
      "roots": [{"role": "all", "path": "C:\\projects\\hello-capp"}]
    }
  ]
}

Import replaces the open project's layout metadata; it does not merge an arbitrary second project or copy, move, edit or delete source. Component IDs must be unique, a source path may appear only once, and a supplied project ID must match the open project. Review the replacement confirmation and export the existing layout first. The importer rejects files larger than 2 MB. The project-layout schema describes the portable format; the host also checks that your local directories are usable.

When using the layout on another computer, update the local paths. Treat the JSON as potentially private: even though these paths are not published as product metadata, an exported layout can reveal your folder names.

Source ownership

Normal project linking and compilation do not overwrite your linked source. Agent source edits are a separate operation governed by the selected workflow and its approval policy. Do not assume every write will show a new confirmation: new built-in Agent sessions can automatically approve already-granted actions. Use the Agent approval controls before granting source changes.

Project state, source snapshots and previously compiled releases are different records. Updating source links does not rewrite an old release, and a visible old result is not evidence that your latest source was compiled.

Project and package icons

Creating a project with source, refreshing its source or compiling can detect a local favicon or logo. Projects displays the primary application's icon; Build's App icon shows the selected image and its origin. Detection does not edit source, run it or download a remote logo.

Choose an image for a manual override. Detect from source returns to automatic selection; Use cApp fallback deliberately keeps the default icon. Choices are per application component. In automatic mode, packaging an older release uses its retained source rather than today's linked files. Detection supports local icon links, static web manifests and conventional filenames; use a static PNG when automatic selection cannot use an image.

Troubleshooting

What success looks like

The intended project is active, each independent app has its own component, and its source roots point to the correct local folders. Build's analysis describes that app rather than an unrelated sibling. Continue with Compile, package and release, then Use the Sidecar Library. Project-authored help is covered in Guide and knowledge.