# UCM User Guide

Welcome to the Universal Context Manager (UCM) User Guide. This comprehensive documentation covers all aspects of using the UCM web interface, from browsing content to managing repositories and implementing AI governance policies.

## Purpose

This guide is designed for:
- **End Users:** Learn how to navigate and use the UCM platform
- **Administrators:** Understand account and organisation management
- **AI Assistants:** Provide context for helping users with UCM-related tasks
- **Developers:** Understand the UI structure for integration purposes

## Guide Structure

The UCM User Guide is organized into logical sections covering different aspects of the platform:

### 1. Landing Pages and Core Information

**Home Page**
- Main landing page overview
- Core pillars of UCM (AI Memory, AI Governance, Knowledge Sharing, Agents)
- Interactive feature cards
- Value propositions and call-to-action sections
- Navigation structure

**About Page**
- UCM mission and architecture
- Core components
- Repository structure and namespace paths
- MCP server integration overview
- API keys and authentication concepts
- How UCM works (3-step process)

**Landing Pages Overview**
- For Developers page (AI memory system for developers)
- For Teams page (GitHub for AI - team collaboration)
- Governance page (Enterprise AI policy enforcement)
- Common elements across landing pages
- Setup instructions and pricing tiers

### 2. Content Browsing and Exploration

**Browse Section**
- Browse hierarchy (Author → Repository → Category → Subcategory → Artifact)
- Navigation through UCM's namespace structure
- Author and repository listings
- Category and subcategory exploration
- Artifact viewer with syntax highlighting
- Edit mode for content owners
- Search and filtering capabilities

### 3. Authentication and Account Management

**Authentication and Account**

**Authentication Pages:**
- Sign In / Sign Up
- Email verification workflow
- Forgot password / Reset password flows
- Authentication error handling

**Account Management:**
- Account dashboard and navigation
- Profile management
- Security settings (password, 2FA, sessions)
- Account settings and preferences
- **API Keys page** (MCP server configuration)
- Author profile management
- Organisation profile (for org members)
- Organisation users and invitations
- Organisation permissions management

### 4. Repository and Policy Management

**Repository and Policy Management**

**Repository Management:**
- Repository dashboard and listings
- Create repository workflow
- Repository overview and statistics
- Repository settings (immutable name, editable details)
- Delete repository (with confirmation)

**AI Governance - Policy Management:**
- Policy dashboard (organisation-scoped)
- Create policy (markdown-based)
- Policy detail view and editing
- Policy assignments (organisation, author, repository, recents, agent)
- Add assignment workflow with target selection
- Policy injection into AI conversations

### 5. OAuth and API Integration

**OAuth and API Documentation**

**OAuth Authorization:**
- OAuth authorization page (authorization code flow with PKCE)
- Device authorization page (for MCP clients)
- OAuth callback pages (success and failure)
- OAuth documentation and implementation guide

**API Documentation:**
- Interactive Swagger UI (`/docs/api`)
- Endpoint categories and testing
- Authentication with API keys
- Request/response examples
- HATEOAS links

**MCP Server Integration:**
- Remote MCP endpoint configuration
- Local MCP server setup (Claude Code and Claude Desktop)
- MCP tools and capabilities

### 6. Extended Account Management

**Extended Account Management**

**Organisation Management:**
- My Organisations page (switch between personal and organisational authors)
- Convert to Organisational Account (irreversible transformation)
- Leave Organisation workflow

**Team Management:**
- Team Authors management
- External LLM Agents (OpenAI integrations)
- External Connections (MCP server connections)
- Service Accounts (automation and API access)
- Security Groups (team-based permissions)

**Invitation System:**
- Accept Organisation Invitation page
- Email-based invitation workflow
- Token validation and security

### 7. How-To Guides and Workflows

**How-To Guides**

**Guides Main Page:**
- Workflow selection hub
- Two modes: Reader vs Author
- Always start with "Connect to the UCM"

**Getting Started:**
- 1-Minute Quick Start (no downloads, no API keys)
- Remote MCP server connection to Claude Desktop
- Advanced local MCP server setup for developers
- Configuration for Claude Desktop, Claude Code CLI, Continue.dev

**Build Your First App:**
- Complete prompt template for new applications
- Three-phase process (Planning, Design, Sprint)
- Example TODO List app workflow
- Micro-block architecture patterns
- UCM guidance integration

**Human-AI Peer Programming Process:**
- Three-phase collaborative methodology
- Planning Phase (requirements and specifications)
- Design Phase (architecture and implementation plans)
- Sprint/Increment Phase (build small, stop, review, iterate)
- Documentation-driven development
- Continuous learning and reflection

### 8. Legal and Compliance

**Legal Pages**

**Terms of Service:**
- Service description and definitions
- User responsibilities and warranties
- Prohibited content and conduct
- AI agent and MCP usage terms
- Intellectual property and licensing
- Special Utaba repository licensing (CC0 public domain)
- Private vs Published content rights
- Disclaimers and limitation of liability
- Dispute resolution and arbitration

**Privacy Policy:**
- Information collection (account, content, technical, AI integration)
- Data usage and sharing policies
- Public vs private content privacy
- Service providers and legal requirements
- Data storage and security measures
- User rights under Australian privacy laws
- International transfers and compliance
- Cookies and tracking
- Children's privacy

## UCM Namespace Structure

All UCM content follows a hierarchical namespace pattern:

```
{author}/{repository}/{category}/{subcategory}/{filename}[@version]
```

**Components:**
- **{author}** - Content owner (e.g., `9684660910`)
- **{repository}** - Logical grouping (typically `main`)
- **{category}** - High-level type (`commands`, `guidance`, `patterns`, `implementations`, `services`, `testing`, `contracts`)
- **{subcategory}** - Specific functional area (e.g., `micro-block`, `user`, `auth`)
- **{filename}** - File with extension (e.g., `README.md`, `MyFile.md`)
- **{version}** - Optional semantic version (e.g., `@1.0.0`)

**Example Paths:**
```
9684660910/main/patterns/micro-block/README.md
9684660910/main/guidance/api-standards/conventions.md@2.1.0
```

## Key User Flows

### Getting Started

1. **Create Account**
   - Navigate to `/auth/signup`
   - Fill out registration form
   - Verify email address
   - Sign in at `/auth/signin`

2. **Get API Keys**
   - Navigate to `/account/api-keys`
   - Copy Author ID and Auth Token
   - Configure MCP server (Remote or Local)

3. **Browse Content**
   - Start at `/browse`
   - Select author
   - Navigate through repositories and categories
   - View artifacts

### Publishing Content

1. **Create Repository** (if needed)
   - Navigate to `/repository/create`
   - Enter repository name (immutable)
   - Add description and details

2. **Upload Artifacts**
   - Use MCP server tools (recommended)
   - Or use REST API directly
   - Follow namespace structure

3. **Manage Content**
   - Browse to your artifacts
   - Edit content directly in browser
   - Update versions and descriptions

### Implementing AI Governance

1. **Access Organisation Settings**
   - Navigate to `/account/org-profile`
   - Verify organisation membership

2. **Create Policy**
   - Navigate to `/org/{orgId}/policies/create`
   - Define policy in markdown
   - Set policy type (Security, Compliance, Quality)

3. **Assign Policy to Targets**
   - Navigate to policy assignments
   - Add assignment (organisation, author, repository, agent)
   - Policy automatically injected into AI conversations

4. **Verify Policy Injection**
   - Connect AI assistant with MCP server
   - Access UCM content
   - AI automatically receives and follows policies

### Team Collaboration

1. **Create Organisation** (if not exists)
   - Convert individual account to organisation
   - Navigate to `/account/org-create`

2. **Invite Team Members**
   - Navigate to `/account/org/users/invite`
   - Enter email and assign role
   - Member receives invitation email

3. **Create Shared Repository**
   - Create organisation-level repository
   - Team members access via organisation authors

4. **Manage Permissions**
   - Navigate to `/account/org/permissions`
   - Assign roles to groups
   - Control access to repositories and policies

## Navigation Patterns

### Main Navigation Header

Present on all pages:
- **UCM** (logo) - Return to home
- **Developers** - Developer landing page
- **Teams** - Teams landing page
- **Enterprise** - Governance landing page
- **Browse** - Content browsing
- **How To...** - Guides dropdown
- **API Docs** - Swagger UI
- **Support** - External support link
- **User Account Dropdown** - Account management

### Breadcrumb Navigation

Used in browse section for hierarchical navigation:
```
Home > Browse > utaba > main > patterns > micro-block > README.md
```

Click any breadcrumb level to navigate back up the hierarchy.

### Sidebar Navigation

Used in account and repository sections:
- **Account Sidebar:** Profile, Security, Settings, Preferences, API Keys, Organisation
- **Repository Sidebar:** Overview, Settings, Browse
- **Policy Sidebar:** Dashboard, Create, Templates, Compliance

## Common UI Patterns

### Cards and Lists

**Author Cards:**
- Display author name, ID, organisation
- Click to view repositories

**Repository Cards:**
- Show repository name, description, artifact count
- Click to view categories

**Policy Cards:**
- Display policy name, type, assignment count
- Click to view/edit policy

### Forms and Validation

**Common Form Patterns:**
- Required fields marked with asterisk (*)
- Real-time validation feedback
- Error messages displayed inline
- Success notifications after submission

**Confirmation Dialogs:**
- Destructive actions require confirmation
- Critical deletions require typing name to confirm
- Loading states during async operations

### Content Viewing and Editing

**File Viewer:**
- Syntax highlighting for code files
- Markdown rendering for .md files
- Copy to clipboard button
- Download file button

**File Editor:**
- Simple textarea editor (owners only)
- Save/Cancel actions
- Version control options
- Description updates

## Australian English Spelling

**Important:** All user-facing text in the UCM UI uses Australian/British English spelling:

**Common Terms:**
- Organisation (not Organization)
- Authorise (not Authorize)
- Colour (not Color)
- Centre (not Center)
- Customise (not Customize)

**Technical Exceptions:**
- API fields and code remain American (e.g., `organizationId`)
- Interface names use American spelling (e.g., `OrganizationMember`)
- File names and technical identifiers unchanged

## Accessibility Features

**Keyboard Navigation:**
- All interactive elements keyboard accessible
- Tab order follows logical reading flow
- Skip links for main content

**Screen Readers:**
- Semantic HTML structure
- ARIA labels for interactive elements
- Proper heading hierarchy
- Form label associations

**Visual Design:**
- High contrast colour schemes
- Focus indicators for keyboard users
- Consistent visual hierarchy
- Responsive design for mobile accessibility

## Technical Architecture

**API:** REST API with HATEOAS links
**Authentication:** Session-based with secure cookies

## Security Considerations

**Authentication:**
- Session-based authentication with secure cookies
- HTTPS only for all communications
- Email verification required
- Password strength requirements
- Rate limiting on sensitive endpoints

**Authorization:**
- Server-side permission checks
- Organisation-based access control
- Repository ownership validation
- Policy assignment permissions

**Token Security:**
- API tokens securely generated and hashed
- Tokens grant full account access (treat as passwords)
- Regeneration supported if compromised
- Never commit tokens to source control

## Getting Help

**Within UCM:**
- **Support Link:** Navigation header → Support (https://utaba.ai/contact)
- **How To Guides:** Navigation header → How To... dropdown
- **API Documentation:** /docs/api - Interactive API reference
- **OAuth Documentation:** /docs/oauth - OAuth implementation guide

**Additional Resources:**
- **Utaba AI Website:** https://utaba.ai
- **Terms of Service:** /terms
- **Privacy Policy:** /privacy

## For AI Assistants

When helping users with UCM-related tasks:

1. **Load Relevant Guide Sections:**
   - Refer to specific guide sections for detailed workflows
   - Use namespace structure when referencing content
   - Follow British English spelling conventions in responses

2. **Common User Questions:**
   - "How do I set up MCP?" → See Authentication and Account guide section
   - "How do I create a policy?" → See Repository and Policy Management guide section
   - "How do I browse content?" → See Browse Section guide
   - "How do I upload artifacts?" → See MCP tools or API documentation

3. **Navigation Assistance:**
   - Provide exact URLs when directing users to pages
   - Explain breadcrumb navigation for browse section
   - Reference sidebar navigation for account/repository areas

4. **Troubleshooting:**
   - Check authentication status first
   - Verify email verification for new accounts
   - Confirm organisation membership for org features
   - Review permissions for restricted actions

## Document Maintenance

**Last Updated:** 2025-11-17
**Version:** 2.1.0
**Coverage:** Complete UI documentation as of v2.1.0

**Update Process:**
When UI changes:
1. Update relevant guide section
2. Capture browser screenshots if needed
3. Verify code references
4. Update this README if structure changes
5. Update version and last updated date

---

**Note to AI Assistants:** This guide provides comprehensive coverage of the UCM web interface. Use it to help users navigate, understand features, and accomplish tasks within the UCM platform. Always verify current UI state when helping users, as interfaces may evolve beyond this documentation.