---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: User_Manual
status: active
tags:
- client/oliver
- domain/ai
- tech/azure-ad
- tech/claude
- tech/react
- tech/typescript
- type/sop
type: sop
---

# GMAL Scope Builder User Manual

## What This Tool Does

The GMAL Scope Builder is a web application designed for agencies to efficiently scope new client ratecards and team structures. It works by matching client briefs against a standardized master asset database (GMAL) using AI (Claude Opus 4.6). 

Key capabilities include:
- **Automated Asset Matching**: AI matches client requirements to standardized GMAL assets.
- **Ratecard Building**: Automatically calculates hours per role based on matched assets.
- **Team Shaping**: Calculates team Full-Time Equivalent (FTE) headcount.
- **Cost Tracking**: Monitors AI usage costs and token consumption.

## Who Uses It

- **Project Managers/Scopers**: Primary users who create new projects, input client briefs, and review AI-generated scopes.
- **Administrators**: Users with 'admin' role who can manage GMAL data (ingest new master files), edit the GMAL database, and manage user accounts.
- **Viewers**: Users who can view existing projects and GMAL assets but cannot create new scopes or modify data.

## How to Access

1. Navigate to the application URL in your web browser.
2. **Authentication**: You will be redirected to the Microsoft login page. Sign in with your Oliver Agency Microsoft account.
   - *Note*: Local development environments can bypass SSO by setting `VITE_DEV_AUTH_BYPASS=true` in the `.env` file.
3. Once logged in, you will see the **Dashboard** (Projects list).

## Main Workflows

### Workflow 1: Creating a New Project Scope

1. **Navigate**: Click the **"+ New Project"** button on the Dashboard (available to Editors/Admins).
2. **Enter Details**:
   - **Project Name**: e.g., "Acme Corp Q2 2025 Scope".
   - **Client Name**: The client's name.
   - **Description**: Paste or type the client brief/requirements.
   - **Model Type**: Select the appropriate AI model type from the dropdown. 
     - *Tip*: If selecting an "AI efficiency" model type, do not apply additional AI efficiency profiles to avoid double-counting hours.
3. **Submit**: Click **"Create Project"**. You will be redirected to the **Project View** page.
4. **Review**: The AI will process the brief. Review the matched assets, suggested hours, and team composition.

### Workflow 2: Viewing Projects

1. **Dashboard**: View all your projects with their current status (Draft, Parsing, Matching, Review, Building, Finalized).
2. **Status Indicators**: 
   - Green: Finalized
   - Blue: Matching/Parsing
   - Yellow: Draft/Building
   - Grey: Draft (Muted)
3. **Click a Project**: Opens the detailed **Project View** to inspect or edit the scope.

### Workflow 3: Managing GMAL Data (Admins Only)

1. **Ingesting New Data**: 
   - Click **"Ingest GMAL Data"** on the Dashboard.
   - Confirm the action. This reloads all assets from the master Excel file.
   - *Warning*: This process updates the entire database. Ensure the correct Excel file is in the `data/` directory.
2. **Editing GMAL Assets**: 
   - Navigate to **"GMAL Editor"** (Admin only).
   - Use the interface to search, view, and modify assets, roles, and hourly records in the GMAL master database.

### Workflow 4: Browsing Assets

1. Navigate to **"GMAL Browser"** from the sidebar.
2. Search the standardized asset database to understand available resources and standard rates.

## FAQ

**Q: Why does the AI cost tracker show increasing costs?**
A: The app uses Claude Opus 4.6 for AI matching. Costs accumulate based on input/output tokens and the number of API calls. You can monitor this in real-time via the "AI Cost" widget in the app.

**Q: Can I edit the client brief after creation?**
A: Yes, on the Project View page, you can modify the description or other parameters and re-run the AI matching process.

**Q: What is the difference between "Model Type" options?**
A: Different model types account for different levels of AI efficiency in the hourly rates. Some models have AI efficiency built-in; others do not. Selecting the correct type prevents double-counting efficiency gains.

**Q: I don't see the "Admin" menu items.**
A: You need the 'admin' role assigned to your user account. Contact your system administrator if you believe you should have access.

**Q: How is FTE calculated?**
A: FTE is calculated based on the total hours required for all matched assets, divided by the standard annual working hours for a full-time employee.

## Related
- [[01 Projects/build-a-squad/USER_MANUAL]]
- [[01 Projects/gmal-scope-builder/DEVELOPER_MANUAL.md]]