# Fabric: first-time setup

Use these steps on the Mac that will run your agents. Get the latest installer and your team's
approved agent package from your Fabric maintainer. This guide includes the updated **Import setup
bundle** and **Live-data repository** Settings controls; if either is missing, update Fabric first.

## 1. Install and open Fabric

1. Close Fabric and Fabric Studio if they are running.
2. Double-click the installer ZIP to extract it.
3. Open **Fabric Installer.app** and follow the prompts. The installer prepares Ollama and
   `nomic-embed-text`, verifies semantic retrieval, and then installs Fabric. Wait for installation
   to finish; the first install requires a network connection.
4. Open **Fabric.app** (Fabric) from your user Applications folder. In Finder, choose
   **Go → Go to Folder**, enter `~/Applications`, and open Executor.
5. Wait for the **Backend** panel to show **Ready**. Keep your existing Fabric settings and data
   when upgrading; you do not need to delete them.

## 2. Complete the setup assistant

Open **Settings → General → Open setup assistant**. Complete your profile. Semantic retrieval is
already ready because the installer verified `nomic-embed-text`. If you selected the additional
**Fabric Local AI** models, wait for their routing, code, and vision downloads to finish before
running a fully local agent. If your team uses an approved cloud or hybrid provider, configure that
provider in **Settings → AI · Models** instead.

## 3. Import your team's setup, if provided

1. Open **Settings → General → Setup and transfer → Import setup bundle**.
2. Select the setup ZIP supplied by your team. This is a setup bundle, not the installer ZIP.
3. Review the preview. Preserve existing items unless you intend to replace them; replacement
   creates backups before applying changes.
4. Confirm the import. Review its result and any warnings.
5. If an environment profile was imported, select it under **Environment profile** and click
   **Apply** when you are ready. Import saves it as a draft; it does not automatically activate it.
6. Review the paths in the next step on this Mac. A teammate's folder locations may differ.

Setup bundles transfer supported non-secret configuration, RAG source definitions and shareable
skills. They do not transfer login tokens, private conversations, run history or a ready-to-use RAG
index. Sign in to services yourself. Agents are imported separately in step 6.

## 4. Set your project folders

Ask your team for access to the required repositories and clone them using your usual Git client.
The Fabric installer does not include game repositories.

For Offers work, you need both the game/Unity project and the separate **gotm_livedata** repository.
An empty folder with the right name is not a Git checkout.

Open **Settings → General → Paths**, then use **Browse** to select the folders on this Mac:

| Setting | What to select |
| --- | --- |
| Unity project | The game project folder containing `Assets` and `ProjectSettings`. |
| Development code root | Your team's configured game code folder, usually the game's `client` folder. |
| Live-data repository | The root of your `gotm_livedata` Git checkout. |

Click **Save paths**. If Fabric shows a pending restart, wait until no jobs are running, expand
the **Backend** panel, click **Restart**, and wait for **Ready**.

For example, if you cloned into your Documents folder, choose the actual folder:

```text
~/Documents/GitHub/gotm_livedata
```

Use Browse to resolve it to this Mac's absolute path. Do not include quotation marks or a
backslash before the underscore.

## 5. Connect the services your agent needs

Open **Settings → Connectors** and configure the required services:

- **Jira:** enter your own connection details and token, then test the connection.
- **Perforce:** select the `p4` command, server, user, client and exact workspace root. Click
  **Save & test**. Resolve workspace-root mismatches before running.
- **Photoshop:** open Photoshop and pair the Fabric UXP plugin using the instructions in Settings.
  Having Photoshop installed is not the same as having its bridge connected.
- **Unity:** open the correct project, start its MCP bridge and use the matching host/port in
  Fabric. Click **Save & test**.
- **Git/GitHub:** configure the account and access required by your team's repositories. A local
  clone alone does not establish permission to fetch or publish.

For **Google Sheets**, the **Sign in with Google** button is disabled until a registered Google
**Desktop OAuth client JSON** has been imported in that section. Ask your Fabric maintainer for
the client file. After importing it, click **Sign in with Google** and complete Google's browser
consent prompts with your own account. If no client is available, Google sign-in cannot be enabled
yet. A saved login does not grant access to a sheet your account cannot open; sheet writes also
require the workflow's approvals. Do not enter your Google password into Fabric.

Optional connectors may remain unconfigured. Resolve warnings for the services your chosen agent
actually requires.

## 6. Import your agent and prepare its knowledge

1. Open **Pipeline → Import agent** and choose your team's approved, signed `.forge-agent` file.
2. Check the import result. A valid independently Fabric Intelligence-certified package with satisfied
   dependencies can be ready for manual governed runs without a second commissioning step.
   Other valid imports stay disabled until admission requirements are met. Automatic routing,
   production-effect authority and run approvals are not granted by this import.
3. Open **Settings → Knowledge**, review the RAG sources and click **Build knowledge index** or
   **Rebuild knowledge index** after connecting their accounts. Hybrid setups show
   **Refresh governed index**. Wait for the result and resolve required sources that cannot be read.
   Importing source definitions does not copy the indexed content.
4. Run **Settings → General → Run health check** and resolve failures relevant to your workflow.

## 7. Run your first ticket

1. Select the correct agent in **Pipeline**.
2. Enter the Jira ticket and all required inputs. A faction workflow may also require its explicit
   faction/member manifest; use the correct agent and the team's approved input data.
3. Leave **Commit & push** off for the first test. Preparation can still create local files and
   use Photoshop; this setting controls later delivery rather than making the run read-only.
4. Click **Run**. Follow the stage results and review any requested approvals.
5. Review the generated outputs before enabling delivery. Do not repeatedly rerun a failed job
   without checking its error.

## If something fails

| Message or symptom | Next step |
| --- | --- |
| `Live-data repository must be an existing directory` (or older `repository root does not exist`) | Set **Live-data repository** to the real checkout, save, and restart if prompted. |
| `A server-owned Jira snapshot with an explicit typed faction manifest is required` (older builds may mention a faction/member manifest) | Select the intended faction workflow and supply its required manifest. |
| Google sign-in is disabled | Import a registered Desktop OAuth client JSON, then sign in. |
| Unity bridge offline / Photoshop not paired | Open the application and start or pair its bridge; test again. |
| Backend unavailable | Wait for startup. If no work is running, use the Backend controls to restart and check the logs. |
| Emergency-stop authority unavailable | Check the safety section in General Settings and follow its setup instructions; do not bypass an active emergency stop. |

If the problem remains, send your Fabric maintainer the app version, the exact error, the ticket
ID and the relevant log excerpt. Keep passwords and tokens out of screenshots and shared logs.

Full handbook: https://fabric-wiki.pages.dev/