# Job Info - Enforcement Rules & Guidance

**Production-Ready Documentation Suite**

This folder contains complete enforcement rules, patterns, and guidance for the Job Info application. All developers must follow these rules for consistency, quality, and professionalism.

---

## 📚 Documentation Index

### Quick Navigation
- **Start here:** [INDEX.md](./INDEX.md) - Task-based navigation
- **Getting started:** [ONBOARDING.md](./ONBOARDING.md) - 5-minute quick start
- **Core rules:** [RULES.md](./RULES.md) - **MOST IMPORTANT** - Read first
- **Visual diagrams:** [FLOWMAP.md](./FLOWMAP.md) - Application flows
- **UI patterns:** [VIEWS.md](./VIEWS.md) - View architecture
- **Tech stack:** [TECH_STACK.md](./TECH_STACK.md) - Technology versions

### Summary
- **Overview:** [DOCUMENTATION_SUMMARY.md](./DOCUMENTATION_SUMMARY.md) - What was created

### Implementation
- **Auth code:** [auth-universal.js](./auth-universal.js) - Single PocketBase auth

---

## 🚀 Quick Start

### For New Developers
1. Read [INDEX.md](./INDEX.md) (2 min)
2. Follow [ONBOARDING.md](./ONBOARDING.md) (15 min)
3. Study [RULES.md](./RULES.md) (30 min)

### For Specific Tasks
- Check [INDEX.md](./INDEX.md) - Find your task → Get directed to right doc
- All docs are cross-referenced and searchable

---

## 📋 Key Rules

### Authentication
- ✅ ONE PocketBase token per user (no Graph tokens)
- ✅ Token obtained at login, reused everywhere
- ✅ Token cached in localStorage
- ✅ Clear all auth on sign out

### Caching
- ✅ Cache ALL GET requests in Redis/Valkey
- ✅ Cache key format: `noun:filter:value`
- ✅ TTL: 5-15 minutes (depends on data freshness)
- ✅ Cache invalidation on mutations

### Frontend Styling
- ✅ Use Tailwind CSS utility classes
- ✅ No inline styles
- ✅ No other CSS frameworks

### Code Quality
- ✅ Type all functions (TypeScript strict mode)
- ✅ Handle all errors
- ✅ Log important events
- ✅ Follow naming conventions
- ❌ NO `any` type (except rare justified cases)

### File Handling
- ✅ Support: PDF, Word (.doc/.docx), Images (.jpg/.png/.gif/etc)
- ✅ Categories: Manager Info, Contracts, Submittals, Plans, Other
- ✅ Filter by type and search term

---

## 📁 File Structure

```
auth/
├── README.md                    (This file - overview)
├── INDEX.md                     (Navigation guide - START HERE)
├── ONBOARDING.md               (Getting started)
├── RULES.md                    (Data handling rules - MOST IMPORTANT)
├── FLOWMAP.md                  (Application flows & diagrams)
├── VIEWS.md                    (UI/View architecture)
├── TECH_STACK.md               (Technology versions & usage)
├── DOCUMENTATION_SUMMARY.md    (What was created)
└── auth-universal.js           (Authentication implementation)
```

---

## ✅ Before Committing Code

Use the checklist in [INDEX.md](./INDEX.md):

- [ ] All functions have TypeScript types
- [ ] No `any` type annotations
- [ ] All errors are caught and logged
- [ ] Cache implemented (if GET endpoint)
- [ ] Follows naming conventions
- [ ] Tests pass
- [ ] Code reviewed against RULES.md

---

## 🔍 Getting Help

1. **Check documentation** - 80% of questions answered here
2. **Search relevant doc** - Use browser find (Ctrl+F)
3. **Look for examples** - TECH_STACK.md and VIEWS.md have code samples
4. **Check logs** - logs/server.log and logs/error.log
5. **Ask team** - With problem details, code, and expected behavior

---

## 📖 How These Docs Are Organized

| Document | Purpose | When to Use |
|----------|---------|------------|
| INDEX.md | Navigation | Finding what you need |
| ONBOARDING.md | Getting started | First day, common tasks |
| RULES.md | Enforcement | Before writing code |
| FLOWMAP.md | Understanding | How app works |
| VIEWS.md | UI Development | Building frontend |
| TECH_STACK.md | Development | Setting up environment |

---

## 🎯 What This Folder Provides

- ✅ **Clear Rules** - No ambiguity about what's required
- ✅ **Best Practices** - Industry-standard patterns
- ✅ **Code Examples** - Real examples you can reference
- ✅ **Professional Foundation** - Enterprise-level documentation
- ✅ **Easy Onboarding** - New developers productive in 1-2 hours
- ✅ **Consistency** - All code follows same patterns
- ✅ **Maintainability** - Well-documented decisions

---

## 📞 Documentation Status

- **Version:** 1.0
- **Status:** Production Ready
- **Created:** January 2026
- **Quality:** Professional / Enterprise
- **Coverage:** Complete - All rules and patterns documented

---

**Ready to get started?** → Go to [INDEX.md](./INDEX.md)

## Secrets and Environment
- For frontend, all secrets are handled by PocketBase OAuth (no client secrets exposed).
- For backend/agent flows, use environment variables and server-side code to store secrets securely.
- The module does not expose or require secrets in the frontend.

## Example Test Page
See `auth-test.html` for a safe way to test all flows without affecting your main app.

## Rules for Copilot Instructions
- Always use Auth.use() to set the pattern before requesting tokens. Supported types: 'pb-user', 'pb-agent', 'graph-user', 'graph-agent', or any combination.
- Always use Auth.ensureToken(type) to get a valid token; it will handle refresh and prompt if needed.
- Never store secrets in frontend code; use PocketBase OAuth for user login.
- All login prompts must use the provided popup, never custom dialogs.
- Token keys are immutable: 'pbUserToken', 'pbAgentToken', 'graphUserToken', 'graphAgentToken'.
- User info extraction must use Auth.getUserInfo().
- For agent/app-only tokens, use backend code, environment variables, and optionally Valkey/Redis for secure storage and retrieval.

## FAQ
- **Can I use this in any project?** Yes, as long as you include PocketBase and this module.
- **Does it work for both user and agent tokens?** Yes, with the correct pattern and backend support for agent tokens (including Valkey/Redis for automation).
- **Is the popup customizable?** The style can be changed, but the flow must remain consistent for all projects.
- **How are secrets handled?** Only via backend environment variables for agent tokens; never exposed in frontend.

---
For further integration, see the comments in `auth-universal.js` and the example test page.