# Studio Web Local Workspace — State Reference

Consult when quickstart's Project State Detection sets `project_state = local-workspace`. The lifecycle itself lives in [../quickstart.md](../quickstart.md); this file covers detection, file ownership, and recovery.

## Detection

An ancestor of the agent project directory contains **either** `.sw-path-marker` or `.local/folder.lock` — both are dropped by Studio Web when it actively manages the folder. A `*.uipx` solution manifest does **not** qualify on its own; every UiPath solution has one, including CLI-only and git-cloned solutions never opened in Studio Web.

Inside the agent project itself: `.uipath/local-project-id.json`, `.uipath/studio_metadata.json`, and `.env` with `UIPATH_PROJECT_ID=<guid>`. These confirm but do not by themselves prove Local Workspace — they can also appear in cloud-workspace projects pulled via `uipath pull`.

## Layout

```
<workspace-root>/
└── <SolutionName>/
    ├── .sw-path-marker              # primary detection signal
    ├── .local/folder.lock           # primary detection signal
    ├── <SolutionName>.uipx          # solution manifest (not LW-specific)
    ├── resources/
    └── <AgentDir>/                  # cd here for all uip codedagent commands
        ├── pyproject.toml
        ├── main.py
        ├── <framework>.json
        ├── entry-points.json
        ├── bindings.json
        ├── uipath.json
        ├── project.uiproj
        ├── .env
        └── .uipath/local-project-id.json
```

## Auto-Sync

`.local/folder.lock` indicates Studio Web is watching this directory and propagating local saves to the remote SW project automatically; SW-side edits flow back to the filesystem. Therefore `uip codedagent push` is **not** part of normal iteration — use `push --overwrite` / `pull --overwrite` only as recovery when sync is paused (workspace opened detached, lock expired, remote conflict).

## Files Owned by Studio Web — Do Not Edit

- `project.uiproj` — SW project file.
- `.uipath/local-project-id.json`, `.uipath/studio_metadata.json` — SW sync state.
- `.local/folder.lock` (in solution root) — SW workspace lock.
- `<SolutionName>.uipx`, `.sw-path-marker` (in solution root) — solution manifest and SW path GUID.

You own: `main.py`, `<framework>.json` (coded fields only), `pyproject.toml`, `bindings.json`, `evaluations/`, `entry-points.json` (regenerated by `init`), `uipath.json` (`packOptions`, `runtimeOptions`).

## Schema Sync After Edits

`entry-points.json` is generated from `main.py` — auto-sync does **not** regenerate it. After ANY edit to `main.py` that touches `Input`/`Output`/`State` Pydantic models, TypedDicts, or the entry function's signature — including adding, removing, renaming, or retyping a field — run `uip codedagent init` BEFORE `uip codedagent run`. Otherwise `entry-points.json` advertises stale schemas and the new field is invisible to the runtime and downstream consumers.

Skip `init` only when the edit is purely inside node bodies / helpers (logic, prompts, business rules) and leaves every Pydantic / TypedDict shape and the entry function's signature byte-identical.

## Anti-Patterns

- **Do not run `uip codedagent new`** — overwrites Studio Web scaffolding and orphans the SW project ID.
- **Do not run `uip codedagent push` as part of iteration** — auto-sync covers it; manual `push` is recovery only.
- **Do not delete `project.uiproj`** — Studio Web requires it; auto-sync (or `pull` as fallback) will restore it.
- **Do not change `UIPATH_PROJECT_ID` in `.env`** — it identifies the Studio Web project this folder syncs with. Changing it sends a fallback `push` to the wrong project and breaks auto-sync identity.
- **Do not skip `uip codedagent init` after editing schemas in `main.py`** — auto-sync does not regenerate `entry-points.json`. Any `Input`/`Output`/`State` field add/remove/rename/retype, or entry-function signature change, requires `init` before `run`. See § Schema Sync After Edits.

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `uipath executable not found` on `run` / `eval` | `.venv` not created or `setup --force` not run after creating it | Run quickstart step 2's `local-workspace` venv prep block |
| Local edit not visible in Studio Web after a few seconds | Auto-sync paused (workspace detached, lock expired, network glitch) | Re-open the workspace in Studio Web; if still missing, `uip codedagent push --overwrite` once to reconcile |
| `Your local version is behind the remote version. Aborted!` on a fallback `push` | SW or another local session edited the project while auto-sync was paused | `uip codedagent pull --overwrite`, reconcile, then `push --overwrite` |
| `UIPATH_PROJECT_ID environment variable not found` on a fallback `push` | `.env` missing or `UIPATH_PROJECT_ID` removed | Restore from `.uipath/local-project-id.json`'s `projectId`; auto-sync will reconstitute `.env` after the next save |
| `401 Unauthorized` on a fallback `push` or on `eval --report` | Session expired | Re-authenticate per [../../authentication.md](../../authentication.md) |