# User Guide

A comprehensive guide to using the SharePoint Permissions Visualizer effectively.

## Table of Contents

1. [Getting Started](#getting-started)
2. [Understanding the Interface](#understanding-the-interface)
3. [Basic Workflows](#basic-workflows)
4. [Advanced Scenarios](#advanced-scenarios)
5. [Understanding Effective Permissions](#understanding-effective-permissions)
6. [Risk Assessment](#risk-assessment)
7. [Common Patterns](#common-patterns)
8. [Troubleshooting](#troubleshooting)
9. [Best Practices](#best-practices)
10. [Real-World Examples](#real-world-examples)

---

## Getting Started

### Opening the Tool

1. Locate `sharepointpermissions.html` on your computer
2. Double-click to open in your default browser
3. OR right-click → Open With → Choose browser

**System Requirements:**
- Modern web browser (Chrome, Firefox, Safari, Edge)
- No internet connection required
- No installation needed

### First Launch

When you open the tool, you'll see:
- A sample scenario already loaded ("Contoso Marketing")
- Three panels: Build (left), Structure (middle), Effective Permissions (right)
- A toolbar at the top with action buttons

**Quick Orientation:**
1. Click items in the middle panel to select them
2. Watch the left and right panels update
3. Toggle the "Inherit" checkbox and see what changes
4. Click "Export Audit (CSV)" to see a report

---

## Understanding the Interface

### Layout Overview

```
┌────────────────────────────────────────────────────────────┐
│                        TOOLBAR                             │
│  [Start New] [Load Sample] [Save] [Load] [Export] [Test]  │
└────────────────────────────────────────────────────────────┘
┌───────────────┬──────────────────┬──────────────────────────┐
│               │                  │                          │
│   BUILD       │   STRUCTURE      │   EFFECTIVE PERMISSIONS  │
│   PANEL       │   PANEL          │   PANEL                  │
│   (Step 1)    │   (Step 2)       │   (Step 3)               │
│               │                  │                          │
│ • Edit item   │ • Tree view      │ • Risk level             │
│ • Toggle      │ • Click to       │ • Inheritance chain      │
│   inherit     │   select         │ • Who has access         │
│ • Grant       │ • Visual         │ • Why they have access   │
│   permissions │   indicators     │ • Explanations           │
│ • Create      │                  │                          │
│   links       │                  │                          │
│ • Manage      │                  │                          │
│   people      │                  │                          │
│               │                  │                          │
└───────────────┴──────────────────┴──────────────────────────┘
```

### Visual Indicators

**In Structure Panel:**

| Icon | Meaning |
|------|---------|
| 🏠 | Site (root) |
| 📚 | Library |
| 📁 | Folder |
| 📄 | File |
| 📤 | Has sharing links |

**Badges:**

| Badge | Color | Meaning |
|-------|-------|---------|
| inherits | Green | Gets permissions from parent |
| unique perms | Yellow | Has broken inheritance |

**Risk Colors:**

| Color | Level | Examples |
|-------|-------|----------|
| 🟢 Green | Low | No obvious risks |
| 🟡 Yellow | Medium | Many editors with unique permissions |
| 🔴 Red | High | Anonymous links, external editors |

---

## Basic Workflows

### Workflow 1: Exploring the Sample

**Goal:** Understand how permissions flow in a realistic scenario

**Steps:**

1. **Load the sample**
   - Click "Load Sample" button
   - See "Contoso Marketing" site appear

2. **Select the site**
   - Click "Contoso Marketing" in the middle panel
   - Left panel shows who has access at the site level
   - Right panel shows effective permissions

3. **Navigate down the tree**
   - Click "Documents" library
   - Notice: inherits from site
   - Right panel: same people have access

4. **Find broken inheritance**
   - Click "Campaigns" folder
   - Notice: yellow "unique perms" badge
   - Right panel: inheritance chain stops here
   - Only Bob Jenkins has access (via Campaigns assignment)

5. **See sharing link effects**
   - Click "Q4 Launch" folder
   - Right panel shows "Anyone with the link" (anonymous!)
   - Risk level: HIGH (red badge)
   - Read the warning about parent folder links

6. **Examine the file**
   - Click "Plan.docx"
   - Right panel: see all sources of access
   - Notice: "Anyone" link still applies (inherited from Q4 Launch)

**Key Takeaway:** Permissions flow down unless inheritance is broken, but sharing links ALWAYS flow down.

---

### Workflow 2: Creating a Simple Structure

**Goal:** Build your own scenario from scratch

**Steps:**

1. **Start fresh**
   - Click "Start New Scenario"
   - See "New Site" with default groups

2. **Add a library**
   - Site is auto-selected
   - Click "Add Library"
   - Type a name (e.g., "Policies")
   - Press Enter or Tab

3. **Add a folder**
   - Library is now selected
   - Click "Add Subfolder"
   - Name it "Executive Policies"

4. **Add a file**
   - Folder is now selected
   - Click "Add File Here"
   - Name it "Strategy.docx"

5. **View the hierarchy**
   - Middle panel shows:
     ```
     🏠 New Site
       📚 Policies
         📁 Executive Policies
           📄 Strategy.docx
     ```

**Key Takeaway:** Build hierarchies naturally by adding children to selected items.

---

### Workflow 3: Breaking Inheritance

**Goal:** Create unique permissions on a folder

**Steps:**

1. **Start with sample**
   - Load sample scenario
   - Navigate to a folder that inherits (e.g., "Documents")

2. **Check current access**
   - Right panel: see all company groups have access
   - Access comes from the site level

3. **Break inheritance**
   - Uncheck "Inherit permissions from parent"
   - Watch the right panel update
   - Now: NO ONE has access!

4. **Grant access to specific person**
   - In "Grant access here" section
   - Select a person from dropdown
   - Choose role (e.g., "Edit")
   - Click "Grant"

5. **Verify**
   - Right panel: only that person has access
   - Inheritance chain shows only this folder (stops here)
   - Badge changes to yellow "unique perms"

**Key Takeaway:** Breaking inheritance gives you full control but starts with zero access.

---

### Workflow 4: Creating Sharing Links

**Goal:** Share a folder via link

**Steps:**

1. **Select an item**
   - Click a folder or file in the middle panel

2. **Choose link type**
   - In left panel, expand "🔗 Sharing links" section
   - Select link type:
     - **Anyone**: Anonymous (⚠️ dangerous!)
     - **People in your organization**: All employees
     - **Specific people**: Named users
     - **People with existing access**: No new permissions

3. **Set permission level**
   - Choose role (Read, Contribute, Edit, Full Control)

4. **Create link**
   - Click "Create Link"
   - Link appears in the list below

5. **Observe effects**
   - Right panel: virtual "link" principal appears
   - All child items now show this link access
   - Risk level may increase

6. **Revoke link**
   - Click "Revoke" button next to link
   - Access immediately removed

**Key Takeaway:** Sharing links are powerful but dangerous - they bypass broken inheritance.

---

## Advanced Scenarios

### Scenario 1: Confidential Folder in Shared Library

**Business Need:** Create a confidential subfolder that ONLY executives can access, while the parent library is open to all.

**Challenge:** Parent sharing links will bypass the subfolder's unique permissions!

**Steps:**

1. **Create structure**
   ```
   Site
   └── Documents (Library)
       ├── Public Folder
       └── Executive Confidential (our target)
   ```

2. **Set library permissions**
   - Documents: All Company (Read)
   - Check: Everyone can read public content ✓

3. **Secure confidential folder - WRONG WAY**
   - Executive Confidential: Uncheck "Inherit"
   - Grant: Executives (Full Control)
   - Check right panel: Still LOW risk? ✓
   - **But wait!** What if someone adds a sharing link later?

4. **Simulate the breach**
   - Go back to Documents library
   - Add sharing link: "Anyone with the link" (Read)
   - Now select Executive Confidential folder
   - **DANGER:** Right panel shows "Anyone" link still grants access!
   - Risk level: HIGH
   - Warning: "Parent folder sharing link bypasses unique permissions"

5. **Proper solution**
   - Remove all sharing links from Documents library
   - Use only direct assignment for access
   - Never create sharing links on parent folders of confidential items

**Lesson:** Breaking inheritance does NOT block sharing links. Only solution: don't use sharing links on ancestors of confidential items.

---

### Scenario 2: External Vendor Collaboration

**Business Need:** Give external contractor access to project folder, but not other company content.

**Best Practice:**

1. **Create dedicated library**
   ```
   Site
   └── Vendor Collaboration (Library)
       └── Project Alpha (Folder)
   ```

2. **Break inheritance at library**
   - Vendor Collaboration: Uncheck "Inherit"
   - No site-level groups have access

3. **Add external user**
   - In "Directory" section
   - Add principal: "alice@vendor.example"
   - Kind: external

4. **Grant limited access**
   - Grant alice@vendor.example: Contribute (NOT Edit or Full Control)
   - Why Contribute? Can add/edit files but not delete or change permissions

5. **Add internal project manager**
   - Grant internal PM: Full Control
   - They can manage vendor access

6. **Verify isolation**
   - Select other libraries
   - Confirm: alice@vendor.example has no access

**Risk Assessment:**
- Risk Level: Low (external user properly isolated)
- No "Anyone" links
- No Edit+ for external user
- Inheritance properly broken

---

### Scenario 3: Time-Based Project Access

**Business Need:** Project team needs full access during active phase, read-only after completion.

**Modeling in Tool:**

1. **Active project structure**
   ```
   Site
   └── Projects (Library)
       └── Q4 Campaign (Folder - unique perms)
           ├── Project Team (Full Control)
           └── Deliverables subfolder
   ```

2. **Simulate project completion**
   - Select Q4 Campaign folder
   - Remove Project Team assignment (Full Control)
   - Add Project Team back with Read only
   - Result: Team can still view but not edit

3. **Alternative: Archive pattern**
   - Create new structure:
     ```
     └── Archive (Library - unique perms)
         └── Q4 Campaign (moved here)
             └── All Staff (Read)
     ```

**Lesson:** Use tool to plan before making changes in production SharePoint.

---

## Understanding Effective Permissions

### How Permissions Accumulate

**Rule 1: Highest Role Wins**

If Alice has:
- Read from Site
- Contribute from Library
- Edit from Folder

Alice's effective permission: **Edit**

**Rule 2: Multiple Sources**

Bob can gain access through:
1. Direct assignment to Bob
2. Membership in a group that's assigned
3. Sharing links (Anyone, Org, Specific)

Tool shows ALL sources in the "Granted at" column.

**Rule 3: Inheritance Stops at Broken Inheritance**

```
Site (Alice: Edit)
├── Library (inherits)
│   └── File1 → Alice: Edit ✓ (inherited from Site)
└── Folder (UNIQUE, Bob: Contribute)
    └── File2 → Alice: NO ACCESS ✗ (inheritance broken)
                 Bob: Contribute ✓ (inherited from Folder)
```

**Rule 4: Sharing Links Bypass Broken Inheritance**

```
Site
└── Library (🔗 Anyone: Read)
    └── Folder (UNIQUE, Alice: Edit)
        └── File → Alice: Edit (from Folder)
                   Anyone: Read (from Library link, BYPASSES unique perms!)
```

### Reading the Effective Permissions Table

**Columns:**

1. **Person/Group**: Name or link type
2. **Type**: User, Group, Guest, or Link
3. **Permission**: Highest role
4. **Granted at**: Sources with explanations

**Example:**

| Person/Group | Type | Permission | Granted at |
|-------------|------|------------|------------|
| Alice | User | Edit | Site (Edit), Library (Contribute) |
| Marketing Team | Group | Read | Library (Read) |
| Anyone with the link | Link | Read | via "Anyone with the link" link on Folder (Read) ⚠️ BYPASSES INHERITANCE |

**Interpreting:**
- Alice has Edit (highest of Site Edit + Library Contribute)
- Marketing Team has Read from Library only
- Anonymous access via sharing link (WARNING!)

---

## Risk Assessment

### Risk Levels Explained

#### 🔴 HIGH RISK

**Triggers:**
1. **"Anyone" sharing links**
   - Anonymous access (no sign-in required)
   - Link can be forwarded to anyone
   - No way to track who accessed

2. **Sharing links bypassing unique permissions**
   - Parent folder link grants access to child with broken inheritance
   - Confusing and unexpected
   - Often overlooked by admins

3. **External users with Edit or higher**
   - Guests can modify or delete content
   - May accidentally grant further access
   - Compliance risk

**Example Message:**
> "Anyone" sharing link grants anonymous access.

**Remediation:**
- Delete "Anyone" links immediately
- Use "Specific people" links instead
- For external users, grant max of Contribute

---

#### 🟡 MEDIUM RISK

**Triggers:**
1. **Broken inheritance with 5+ editors**
   - Broad access despite unique permissions
   - Harder to audit
   - Increases chance of misconfiguration

**Example Message:**
> Broken inheritance with many editors.

**Remediation:**
- Review if all editors need access
- Consider groups instead of individual assignments
- Document why unique permissions are needed

---

#### 🟢 LOW RISK

**Meaning:**
- No obvious security issues detected
- Still review manually for business context

**Example Message:**
> No obvious risks detected.

**Note:** Low risk doesn't mean zero risk. Always consider:
- Is the right people have access?
- Is anyone missing who should have access?
- Do permission levels match job roles?

---

### Risk Mitigation Patterns

#### Pattern 1: Replace "Anyone" Links

**Before:**
```
Documents
└── 🔗 Anyone: Read
    └── File.docx → ANYONE can access (HIGH RISK)
```

**After:**
```
Documents
└── 🔗 Specific people: Read (specific list)
    └── File.docx → Only named people can access (LOW RISK)
```

---

#### Pattern 2: Eliminate Link Bypass

**Before:**
```
Library
├── 🔗 Org: Read
└── Confidential (UNIQUE)
    └── Secret.docx → WHOLE ORG can access (HIGH RISK)
```

**After:**
```
Library (no links)
├── Public Folder
│   └── 🔗 Org: Read (link moved here)
└── Confidential (UNIQUE)
    └── Secret.docx → Only assigned users (LOW RISK)
```

**Key:** Move sharing links BELOW the unique permission boundary.

---

#### Pattern 3: Downgrade External Access

**Before:**
```
Vendor (external): Edit (HIGH RISK)
```

**After:**
```
Vendor (external): Contribute (LOWER RISK)
PM (internal): Full Control
```

**Rationale:** Contribute allows add/edit but not delete or permission changes.

---

## Common Patterns

### Pattern 1: Default Site Setup

**Use Case:** New team site for department

**Structure:**
```
Department Site
├── {Site} Owners: Full Control
├── {Site} Members: Edit
├── {Site} Visitors: Read
└── Documents (Library - inherits)
    ├── Public (Folder - inherits)
    └── Leadership (Folder - UNIQUE)
        └── Leadership Team: Full Control
```

**Characteristics:**
- Three-tier access (owners, members, visitors)
- Most content inherits (easy to manage)
- Sensitive content isolated with unique permissions

---

### Pattern 2: Project Site

**Use Case:** Cross-functional project team

**Structure:**
```
Project Site
├── Site Owners: Full Control
├── All Project Members: Contribute
└── Project Assets (Library - inherits)
    ├── Deliverables (Folder - inherits)
    │   └── 🔗 Org: Read (stakeholders can view)
    ├── Working Drafts (Folder - inherits)
    └── Archive (Folder)
        └── 🔗 Existing Access: Read (no new permissions)
```

**Characteristics:**
- Single project team permission level
- Deliverables shared broadly via link
- Archive is read-only via special link type

---

### Pattern 3: Vendor Collaboration

**Use Case:** External consultants need isolated workspace

**Structure:**
```
Main Site
└── Vendor Workspace (Library - UNIQUE)
    ├── Internal PM: Full Control
    ├── vendor@example.com: Contribute
    └── Deliverables (Folder - inherits)
        └── 🔗 Specific (PM + vendor): Read
```

**Characteristics:**
- Broken at library level (full isolation)
- External has Contribute (not Edit or Full Control)
- Internal PM has full control for management

---

### Pattern 4: Public Communications

**Use Case:** Company-wide announcements, all staff can read

**Structure:**
```
Communications Site
├── All Staff: Read
├── Comms Team: Edit
└── News (Library - inherits)
    ├── Published (Folder - inherits)
    │   └── 🔗 Org: Read
    └── Drafts (Folder - UNIQUE)
        └── Comms Team: Edit
```

**Characteristics:**
- Open read access to published content
- Drafts isolated from general staff
- Org link for easy sharing of published articles

---

## Troubleshooting

### Issue 1: "I broke inheritance but people still have access"

**Symptom:** Unchecked "Inherit" but effective permissions show site-level groups.

**Cause:** Sharing links on parent folders.

**Solution:**
1. Check parent items for 📤 indicator
2. Select parent in tree
3. Review "Sharing links" section
4. Revoke links OR move confidential content elsewhere

---

### Issue 2: "External user has no access despite assignment"

**Symptom:** Added external user, granted permission, but right panel doesn't show them.

**Cause:** Granted permission on parent, but selected item has broken inheritance.

**Solution:**
1. Check if selected item has "unique perms" badge
2. If yes, grant permission directly on that item
3. Or re-enable inheritance to flow permissions down

---

### Issue 3: "Risk shows LOW but I see external users"

**Symptom:** External users are present but risk is not HIGH.

**Cause:** External users have Read or Contribute (not Edit+).

**Explanation:** Risk heuristic only flags external with Edit or Full Control.

**Action:** Review if Read/Contribute is appropriate for business needs.

---

### Issue 4: "Can't add library under folder"

**Symptom:** "Add Library" button doesn't work.

**Cause:** Libraries can ONLY be direct children of sites.

**Solution:**
1. Select the site (root item)
2. Click "Add Library"
3. To add under existing library, use "Add Subfolder"

**SharePoint Structure Rules:**
```
Site
└── Library ✓
    └── Library ✗ (invalid)
    └── Folder ✓
        └── Library ✗ (invalid)
        └── Folder ✓
        └── File ✓
```

---

### Issue 5: "Exported CSV opens garbled in Excel"

**Symptom:** Foreign characters or special names look corrupted.

**Cause:** Excel assumes ANSI encoding, not UTF-8.

**Solution:**
1. Open Excel first (blank workbook)
2. Data tab → Get Data → From File → From Text/CSV
3. Select your CSV file
4. File Origin: "65001: Unicode (UTF-8)"
5. Click Load

---

## Best Practices

### 1. Start Simple, Break Inheritance Sparingly

**Why:** Every unique permission point increases complexity and maintenance burden.

**Default:**
- Most items should inherit
- Only break inheritance when truly needed

**When to Break:**
- Confidential content (HR, finance, executive)
- External collaboration (isolate vendor access)
- Compliance requirements (need audit trail)

**When NOT to Break:**
- Temporary projects (use groups instead)
- Personal folders (educate users on private files)
- "Just to be safe" (creates confusion)

---

### 2. Use Groups, Not Individual Assignments

**Why:** Managing 10 individuals × 20 items = 200 assignments to track. Managing 2 groups × 20 items = 40 assignments.

**Pattern:**
```
❌ BAD:
Folder
├── Alice: Edit
├── Bob: Edit
├── Carol: Edit
└── ... (10 more people)

✅ GOOD:
Folder
└── Project Team: Edit
    (Group membership managed separately)
```

**Tool Tip:** In the tool, add a group principal and grant once, rather than 10 user principals.

---

### 3. Avoid Sharing Links on Parent Folders of Sensitive Content

**Why:** Links bypass broken inheritance.

**Pattern:**
```
❌ RISKY:
Library
├── 🔗 Org: Read (⚠️ will bypass children's unique perms)
├── Public (Folder - inherits) → Org can read ✓
└── Confidential (Folder - UNIQUE) → Org can STILL read ✗

✅ SAFER:
Library (no links)
├── Public (Folder)
│   └── 🔗 Org: Read (link only on public content)
└── Confidential (Folder - UNIQUE) → No org access ✓
```

---

### 4. Document Permission Decisions

**Why:** Future admins (including yourself) will forget why unique permissions were set.

**In Production:** Use SharePoint item description or OneNote to document:
- Why inheritance was broken
- Who approved the change
- Expected review date

**In Tool:** Use the tool to create "before" and "after" scenarios, export both as JSON for documentation.

---

### 5. Regular Audits with CSV Export

**Why:** Permissions drift over time. Regular reviews catch issues.

**Workflow:**

1. Model current state in tool
2. Export Audit (CSV)
3. Review in Excel:
   - Filter: Risk = High → address immediately
   - Filter: Inherits = No → review if still needed
   - Filter: Sharing Links = not empty → verify appropriateness

4. Make changes in tool first (plan)
5. Apply changes in production SharePoint
6. Save tool scenario as "Current State - [Date].json"

**Frequency:** Quarterly for active sites, annually for archives.

---

### 6. Test Before Implementing

**Why:** Breaking inheritance or revoking access can lock out legitimate users.

**Workflow:**

1. **Model current state**
   - Replicate your SharePoint structure in the tool
   - Add all groups and users

2. **Plan changes**
   - Make desired changes in the tool
   - Check effective permissions before and after
   - Export audit CSV to compare

3. **Review with stakeholders**
   - Show them the tool
   - Walk through effective permissions table
   - Get approval

4. **Implement in production**
   - Make changes in real SharePoint
   - Test with real user accounts

5. **Verify**
   - Update tool to match production
   - Confirm effective permissions match expectations

---

### 7. Principle of Least Privilege

**Why:** Users should have minimum permissions needed to do their job.

**Role Selection Guide:**

| Role | Can Do | Use When |
|------|--------|----------|
| Read | View, download | General staff viewing company news |
| Contribute | Read + add + edit own | Project team collaborating on documents |
| Edit | Contribute + edit all + delete | Team leads managing shared content |
| Full Control | Edit + change permissions | Site owners only |

**Common Mistake:** Granting Edit when Contribute is sufficient.

**Tool Tip:** After granting, check effective permissions table. If user has multiple sources, ensure highest role is appropriate.

---

## Real-World Examples

### Example 1: HR Department Site

**Business Requirements:**
- HR staff: full access
- Managers: read-only access to forms and policies
- General staff: no access (request forms via separate process)

**Tool Setup:**

1. **Create structure**
   ```
   HR Site
   ├── Site Owners (Full Control)
   ├── HR Staff Group (Edit)
   └── HR Documents (Library - inherits)
       ├── Public Forms (Folder - UNIQUE)
       │   └── Managers Group (Read)
       ├── Policies (Folder - UNIQUE)
       │   └── All Staff Group (Read)
       └── Confidential (Folder - inherits from site)
   ```

2. **Verify isolation**
   - Select "Confidential" folder
   - Right panel: only Site Owners and HR Staff have access ✓

3. **Verify manager access**
   - Select "Public Forms"
   - Right panel: Managers have Read, HR Staff have Edit ✓

4. **Check risk**
   - All folders: Low risk (no sharing links, no externals) ✓

**Lesson:** Multiple unique permission points allow fine-grained access control.

---

### Example 2: Customer Project Portal

**Business Requirements:**
- Internal project team: full access
- Customer users: access to deliverables only
- Customer can upload feedback files

**Tool Setup:**

1. **Create structure**
   ```
   Customer Project Site
   ├── Project Team (Full Control)
   └── Project Library (inherits)
       ├── Internal (Folder - inherits)
       │   └── Working Files
       └── Customer Portal (Folder - UNIQUE)
           ├── Project Team (Full Control)
           ├── customer@client.com (Contribute)
           ├── Deliverables (Folder - inherits)
           └── Feedback (Folder - inherits)
   ```

2. **Add customer principal**
   - Name: customer@client.com
   - Kind: external

3. **Grant access**
   - Customer Portal: customer@client.com (Contribute)

4. **Verify**
   - Select "Internal" folder → customer has no access ✓
   - Select "Customer Portal" → customer has Contribute ✓
   - Select "Feedback" → customer can upload (Contribute) ✓

5. **Check risk**
   - Customer Portal: Medium risk (external with Contribute)
   - Review: Contribute is appropriate (can't change permissions) ✓

**Lesson:** Broken inheritance at folder level creates secure sub-portal for external users.

---

### Example 3: Company Intranet

**Business Requirements:**
- All employees: read access to news and policies
- Content team: edit access to publish articles
- No external sharing
- Easy link sharing for popular articles

**Tool Setup:**

1. **Create structure**
   ```
   Intranet Site
   ├── All Staff (Read)
   ├── Content Team (Edit)
   └── Pages Library (inherits)
       ├── News (Folder - inherits)
       │   └── 🔗 Org: Read
       ├── Policies (Folder - inherits)
       │   └── 🔗 Org: Read
       └── Drafts (Folder - UNIQUE)
           └── Content Team (Edit)
   ```

2. **Add org-wide group**
   - Name: All Staff
   - Kind: group

3. **Add content team**
   - Name: Content Team
   - Kind: group

4. **Verify**
   - Select "News" → All Staff Read via site + Org link ✓
   - Select "Drafts" → Only Content Team has access ✓

5. **Check risk**
   - News: Low (org links appropriate for internal comms) ✓
   - Drafts: Low (properly isolated) ✓

**Lesson:** Org-wide links are acceptable for truly public internal content.

---

### Example 4: Legal Hold Archive

**Business Requirements:**
- Legal team: full access
- No one else can access (compliance)
- No sharing links allowed
- Must track all access

**Tool Setup:**

1. **Create structure**
   ```
   Legal Site
   └── Legal Hold (Library - UNIQUE)
       ├── Legal Team (Full Control)
       ├── (no other assignments)
       └── Case Files (Folders - inherit)
   ```

2. **Verify complete isolation**
   - Select "Legal Hold" → only Legal Team ✓
   - Select any subfolder → only Legal Team ✓
   - No sharing links anywhere ✓

3. **Check risk**
   - Legal Hold: Low (properly secured) ✓

4. **Document setup**
   - Export scenario as "Legal_Hold_Permissions.json"
   - Export audit CSV for compliance record
   - Save both in secure location

**Lesson:** Break inheritance at library level for complete isolation. No sharing links ensure no accidental leaks.

---

### Example 5: Merger & Acquisition Data Room

**Business Requirements:**
- Internal deal team: full access
- External advisors: read-only access to specific folders
- Different advisors see different folders
- All access must be auditable
- Time-limited (revoke after deal closes)

**Tool Setup:**

1. **Create structure**
   ```
   Deal Data Room Site
   └── Data Room (Library - UNIQUE)
       ├── Deal Team (Full Control)
       ├── Financial Advisor (Read on Financial Docs only)
       ├── Legal Advisor (Read on Legal Docs only)
       ├── Financial Docs (Folder - UNIQUE)
       │   └── Financial Advisor (Read)
       ├── Legal Docs (Folder - UNIQUE)
       │   └── Legal Advisor (Read)
       └── Internal Only (Folder - UNIQUE)
           └── Deal Team (Full Control)
   ```

2. **Add external advisors**
   - financialadvisor@firm1.com (external)
   - legaladvisor@firm2.com (external)

3. **Grant granular access**
   - Financial Docs: financialadvisor@firm1.com (Read)
   - Legal Docs: legaladvisor@firm2.com (Read)

4. **Verify isolation**
   - Select Financial Docs → only Deal Team + Financial Advisor ✓
   - Select Legal Docs → only Deal Team + Legal Advisor ✓
   - Select Internal Only → only Deal Team ✓

5. **Check risk**
   - Financial Docs: Low (external has read-only) ✓
   - No sharing links ✓

6. **Document**
   - Export "Deal_DataRoom_Pre_Close.json"
   - Save CSV audit for compliance

7. **Plan post-close**
   - Model revocation: remove both external advisors
   - Export "Deal_DataRoom_Post_Close.json"
   - Verify only internal team has access ✓

**Lesson:** Multiple broken inheritance points allow surgical access control. Tool helps plan time-based access removal.

---

## Tips and Tricks

### Tip 1: Use Scenarios for Change Planning

Save before/after states:
1. Model current state → Export "Before_Change.json"
2. Make planned changes
3. Export "After_Change.json"
4. Show stakeholders both scenarios for approval

### Tip 2: Keyboard Shortcuts

- **Escape**: Close help popover
- **Tab**: Move between input fields
- **Enter**: Submit forms (add principal, create link)

### Tip 3: Browser Developer Console

Open console (F12) to:
- Run self-test: `runSelfTest()`
- Inspect state: `console.log(app.state)`
- Find all high-risk items: `app.state.nodes.filter(n => riskOf(n).level === 'High')`

### Tip 4: Quick CSV Analysis in Excel

After export:
1. Open in Excel
2. Apply filters to header row
3. Sort by Risk (High first)
4. Focus remediation on high-risk items

### Tip 5: Bulk Principal Creation

For training scenarios with many users:
1. Open browser console (F12)
2. Run:
```javascript
['Alice', 'Bob', 'Carol', 'Dave'].forEach(name => {
  app.state.principals.push({id: makeId(), name, kind: 'user'})
})
render()
```

### Tip 6: Compare Two Scenarios

To see permission changes:
1. Load scenario A
2. Export CSV as "A_audit.csv"
3. Load scenario B
4. Export CSV as "B_audit.csv"
5. Use Excel or diff tool to compare

---

## Next Steps

### Learning Path

1. ✅ Read this guide
2. ✅ Load sample and explore
3. ✅ Create simple structure from scratch
4. ✅ Practice breaking inheritance
5. ✅ Experiment with sharing links
6. ✅ Review risk assessments
7. ✅ Export and review CSV audit
8. ⬜ Model your real SharePoint site
9. ⬜ Use for change planning
10. ⬜ Conduct quarterly audits

### Resources

- **README.md**: Overview and feature list
- **ARCHITECTURE.md**: Technical deep dive
- **API_REFERENCE.md**: Function documentation

### Getting Help

- Check "What is this?" button in tool header
- Review warning messages (they're educational!)
- Export CSV audit for detailed view
- Run Self-Test to verify tool is working

---

## Glossary

**Assignment**: Direct permission grant (user/group + role + item)

**Breaking Inheritance**: Stopping permission flow to create unique permissions

**Bypass**: When sharing links grant access despite broken inheritance (dangerous!)

**Effective Permissions**: Actual access someone has (combined from all sources)

**Inherit**: Get permissions from parent automatically

**Node**: Any item (site, library, folder, file)

**Principal**: Person, group, or external identity

**Role**: Permission level (Read, Contribute, Edit, Full Control)

**Sharing Link**: URL-based access grant

**Unique Permissions**: Item has broken inheritance (doesn't get parent permissions)

**Virtual Principal**: Synthetic principal representing a sharing link