Manage Folder Permissions & Sharing

Feature Owner: James Derick Billate
Updated by: Christian Denzon
Module: Organization
Priority: Must
Date: July 7, 2026
Last Updated: September 30, 2026

Executive Summary

What is this feature?

Manage Folder Permissions allows Creators and Agency Admins to share their folders with other WyzQuests accounts. It gives folder owners and permitted collaborators a way to assign access levels to project, quest, and adventure folders so content can be viewed, edited, or administered without requiring the owner to manually share content from their own device.

Since the August 2026 core-logic overhaul (v2.0), folder access is resolved across the folder hierarchy: an owner or admin of any parent folder keeps authority over every nested subfolder, a user demoted to Viewer on an ancestor is capped to Viewer for the whole subtree, and only the folder owner or an admin can manage permissions.

Why does it matter?

Without folder permissions and sharing, other accounts cannot access content owned by a Creator or Agency Admin. This limits content reviews, viewing, and collaboration across WyzQuests. Folder Permissions makes folder access more dynamic by allowing selected users to collaborate within organized content spaces. Collaborators with view-or-higher access can now also preview shared content in a read-only learner experience and create their own independent copy via "Use as Template" — enabling reuse without exposing or altering the original.

What's the MVP scope?

  • Permission invite (existing WyzQuests accounts, invited by email).

  • Permission CRUD process.

  • Permission levels: view, edit, admin, and owner.

  • Permission logic for folder access, resolved across the folder hierarchy (owner/admin inheritance, view caps, creator-ownership exception).

  • Folder permission support for project, quest, and adventure folders.

  • Permission management matrix: only the folder owner or an admin may manage permissions; the Admin role can only be granted by the root tree owner.

  • Shared-content preview and "Use as Template" for collaborators with view-or-higher access (v2.0 / Phase 2).

  • Folder management for permitted users: create child folders, move folders and content, permanently delete folders, and bulk content actions (move, archive, delete, restore).


1. User Pain Point & Solution

John created an Agency Admin workspace, invited creators, and created a specified folder. However, he needs to share that folder with others remotely instead of giving access from his own device or manually transferring content. Manage Folder Permissions lets John invite accounts by email and grant the right permission level directly from the Content Library. Because permissions are inherited down the folder tree, John keeps control over everything inside the folders he owns, and collaborators who were granted edit or admin access can safely build their own subfolders inside his tree without locking him out.

Pain Points

  • Emotional: Tired and exhausted from manual sharing and repeated coordination.

  • Functional: Remote users cannot access needed folder content unless the owner manually shares it or exposes content another way.

  • Business: More accounts can efficiently access folders and their content, improving agency workflow and content collaboration.


2. 4D Framework Mapping

Diagnose: Provides another way to check which accounts or users can access content under specific folder permissions.

Design: Generates an overview of shared content and who has permission to access it.

Develop: Further enhances the workflow and organization of team dynamics through folder-based collaboration.

Deliver: Provides more ways to deliver quality output by ensuring content is organized and accessible per folder.


3. User Flows

Entry Points: Agency Admin or Creator logs in and opens Content Library through Library navigation.

Success Criteria: Agency Admin or Creator can open a folder's Permissions modal, add a user by email, assign a permission level, update that permission, revoke access, and see how roles inherit into subfolders. Collaborators with access can preview shared content and create their own template copies.

Main Path (Happy Path)

  1. Sign in as an Agency Admin or Creator.

  2. Click Library or Content Library.

  3. Navigate the dashboard.

  4. Create or select a folder.

  5. Open the folder kebab menu.

  6. Click Permissions.

  7. The modal lists current members: the tree Owner, the literal folder Creator, and collaborators; members inheriting a role from a parent folder are shown as "Inherit from Parent (Role)".

  8. Input the invited user's email.

  9. Select permission level: view, edit, or admin (the Admin role is accepted only from the root tree owner).

  10. Click Share.

  11. System validates folder access (owner/admin only), user existence, and duplicates.

  12. System saves the permission and sends an email notification.

  13. The invited user opens the shared folder from their library ("Shared with you") and can view its content, preview items, or use them as templates.

Permission Resolution (v2.0)

  • Owner/admin authority on any ancestor folder applies to every nested subfolder — the tree owner can never be locked out of their own tree.

  • A Viewer on an ancestor is capped to Viewer for the whole subtree, including folders they created.

  • Exception: a collaborator who created a subfolder while holding owner, admin, or edit on its direct parent keeps their OWNER control over that subfolder chain.

  • A per-folder explicit grant (admin/edit) is authoritative on that folder; a per-folder View row demotes that folder unless an ancestor owner exists.

  • Agency fallback: an agency member with no permission row on a colleague's folder can manage content (agency scope) but cannot move folders or manage permissions.

Permission Management Rules (v2.0)

  • Only the folder owner or an admin (including inherited) can add, change, or remove permissions. Edit and View collaborators cannot manage permissions.

  • No one can change their own role.

  • The root tree owner cannot be modified, demoted, or removed.

  • Admins cannot modify other admins, and can only assign View or Edit.

  • The Admin role can only be granted by the root tree owner.

  • Removing a member's local permission returns them to inherited parent permissions (if any).

Additional Flow — Shared Content: Preview & Use as Template (v2.0)

  1. Collaborator (view or higher) opens a shared folder in their library (badge "Shared with you").

  2. Clicking a shared quest/adventure opens a read-only preview (learner player for quests; adventure preview page for adventures). Progress is not saved; "Back to the folder" exits.

  3. Folder menu (kebab) on non-owned content offers Preview and Use as Template: enter a title and choose a destination folder.

  4. The system creates a fully independent draft copy in the collaborator's library; the original content stays untouched.

Additional Flow — Folder Management (v2.0)

  • Owner, admin, and edit collaborators (including inherited roles) can create child folders inside a folder.

  • Owner/admin can move folders; moving a folder out of a tree requires managing the source tree.

  • Deleting a folder is permanent: its subfolders are deleted and the content inside moves to the library root.

  • Bulk actions (move, archive, delete, restore) follow the same role checks.

No Data: Alert the Agency Admin or Creator that the folder, account, or permission does not exist.

API Error: Terminate the permission process promptly and display the proper error codes and messages.

Permission Denied: Requests without the required role are rejected (403) and the UI hides or disables the corresponding actions. View-only collaborators see only Information in the folder menu.

Decision Points:

  • IF folder exists THEN allow CRUD of folder permissions ELSE halt CRUD of folder permissions.

  • IF invited email belongs to a WyzQuests account THEN add permission ELSE show user not found.

  • IF requester is the folder owner or an admin (including inherited) THEN allow permission changes ELSE deny request (edit and view cannot manage permissions).

  • IF requester is an admin and the target is an admin or the owner THEN deny; IF assigning the Admin role THEN the requester must be the root tree owner.

  • IF the target is the requester's own row THEN deny (no self role changes).

  • IF permission already exists THEN show conflict message ELSE create permission.

  • IF permission is revoked THEN remove the local access (falling back to inherited permissions) ELSE keep current permission.

  • IF a Viewer role exists on an ancestor THEN cap the subtree to view (creator exception applies) ELSE resolve the strongest ancestor owner/admin.


4. Information Architecture

Primary Information

  • Agency or Creator information.

  • Folder information.

  • Invited account information.

  • Permission level information.

  • The requesting user's effective role for the folder.

Secondary Information

  • Folder type: project, quest, or adventure.

  • Folder name.

  • User email.

  • User name.

  • Current permission member list, including the tree Owner marker and the literal folder Creator marker.

  • Inherited roles from parent folders ("Inherit from Parent (Role)").

  • Folder card status labels: Owner / Creator / Shared with you / Shared (with collaborator count).

  • Folder information modal: creator, created and last modified dates, breadcrumbs, content counts (sub-folders, quests, adventures), access level (Private / Shared with N members).

Tertiary Information

  • Email notification status.

  • Permission timestamps.

  • Owner permission marker.

  • Inheritance markers shown to non-owners ("Role (inherited)").

Actions

  • Primary CTA

    • "Permissions"

  • Secondary Actions

    • "Permissions" -> "Add"

    • "Share"

    • "Change Permission" (including "Inherit from Parent")

    • "Revoke Permission"

    • "Done"

    • "Information"

    • "Edit folder", "Delete", "Move Folder" (permission-gated)

    • "Preview" and "Use as Template" (shared, non-owned content)

    • Bulk actions: move, archive, delete, restore


5. Data Requirements

Frontend Needs

  • Agency or Creator information.

  • Folder ID.

  • Folder type.

  • Invited account email.

  • Permission level.

  • Existing folder permission list (members, Owner/Creator markers, inherited roles).

  • User name and email for permission display.

  • The requesting user's effective role per folder (with hierarchy and agency behavior).

  • Folder metadata for the information modal (counts, breadcrumbs, creator).

API Calls Frontend Will Make

  • GET /api/folder/permissions/{folder_id}

  • POST /api/folder/permissions/{folder_id}

  • PATCH /api/folder/permissions/{folder_id}

  • DELETE /api/folder/permissions/{folder_id}

  • Folder CRUD and management: /api/folder/{quest|project|adventure}-folders (list, create, detail, update, delete, move, reorder)

  • Shared content: /api/creator/get-quest, /api/creator/get-adventure, /api/creator/adventure-sequence (?preview=true), POST /api/creator/copy-content


6. Performance Considerations

Database Optimization

  • Ensure necessary Supabase queries are limited to needed columns rather than global fetching.

  • Use indexes on folder_permissions.folder_id and folder_permissions.user_id (implemented).

  • Unique constraint on folder_id and user_id to avoid duplicate permissions (implemented — dedup and unique index).

  • Validate folder ownership and hierarchy before running unnecessary permission mutation work.

  • Clean up permission rows when folders are deleted (implemented via delete triggers).

Query Efficiency (v2.0)

  • Ancestor walks use a single recursive-CTE RPC (get_folder_ancestors) instead of one query per folder level.

  • The folder reachable-set filter used by list routes is memoized per request.


7. Security & Authorization

Who Can Access This Feature?

  • Administrator: No access.

  • Reviewer: No access.

  • Creator: Full access to their own folders; invited access to other accounts' folders at the granted level.

  • Learner: No access.

  • Agency Admin: Full access to their own folders; agency members can manage content inside colleagues' folders (agency fallback), but cannot move folders or manage permissions unless explicitly granted.

Enforcement (v2.0)

  • Only the folder owner or an admin (including inherited) can manage permissions; edit and view collaborators cannot.

  • No self role changes; admins cannot modify other admins; the root tree owner cannot be modified or removed; the Admin role is granted only by the root tree owner.

  • Hierarchy caps apply even to agency members (an explicit Viewer row is never bypassed).

  • All checks are enforced server-side in the API routes; RLS policies on folder_permissions (owner/admin-only writes, owner-row protection) provide a second layer of defense.


8. Error Handling

  • Invalid credentials -> authentication error.

  • Unauthorized users -> cannot request permission operations.

  • Invalid permission payloads -> schema validation error.

  • Non-existent account -> user not found error.

  • Existing permission -> conflict error.

  • Permission changes that violate the management matrix -> forbidden (self role change, modifying another admin, modifying the owner, assigning the Admin role without being the root tree owner).

  • Permission not updated -> internal error.

  • Permission not revoked -> internal error.

  • Failed folders or permissions -> error response.

  • Email notification failure -> the permission remains saved; email delivery is asynchronous and tracked via monitoring.

  • Archived or deleted content/folders -> not found (404).


9. Testing Checklist

Happy Path

  1. Sign in as an Agency Admin or Creator.

  2. Navigate to Library or Content Library.

  3. Create a folder.

  4. Open the folder kebab menu.

  5. Click Permissions.

  6. Add a user email.

  7. Select view permission.

  8. Confirm the user appears in the Members list.

  9. Change permission to edit.

  10. Change permission to admin (as the folder owner).

  11. Revoke the permission.

  12. Confirm revoked user is removed from the list.

  13. Confirm the root tree owner is labeled Owner and a subfolder creator is labeled Creator.

  14. Confirm inherited members show "Inherit from Parent (Role)" on subfolders.

Edge Cases

  • Unauthorized account.

  • Folder not found.

  • Permission not found.

  • User account not found.

  • Duplicate permission invite.

  • Requester only has view access (no permission-management actions available).

  • Invalid email input.

  • Invalid permission level.

  • Folder was deleted after modal opened.

  • Email notification fails after permission is added.

  • Root owner opens a subfolder created by an external collaborator (full control expected).

  • Edit/admin collaborator creates a subfolder inside a shared folder (keeps management over the subfolder chain).

  • User demoted to Viewer on the root (capped for the whole subtree; loses move/delete on nested folders, including folders they created).

  • Admin attempts to modify another admin, or their own role, or the owner (denied).

  • Admin attempts to assign the Admin role (denied unless root tree owner).

  • Agency member without a permission row in a colleague's folder (content actions allowed; folder move and Manage Permissions denied).

  • Preview: no progress is saved; exit returns to the folder/library; the editor route returns 404.

  • Use as Template: draft copy created with content intact; destination picker limited to folders the user can create in; original content unchanged.

  • Folder deletion with subfolders and content: subfolders are removed and content moves to the root.


10. OPEN QUESTIONS

  • Should there be an ability for Agency Admins to organize quests or other content inside the folder? — Addressed (v2.0): agency members can manage content inside colleagues' folders; folder-level actions (move, permissions) remain permission-gated.

  • Should Creators allow Reviewers to also have access to their folders? — Still open. Reviewers currently have no MFPS access.

  • Should parent folder permissions automatically apply to child folders? — Resolved (v2.0, implemented): owner/admin inheritance down the tree with view caps and the creator-ownership exception.

  • Should edit permission allow permission management, or should permission management be admin-only? — Resolved (v2.0, implemented): permission management is limited to the folder owner and admins.

  • Should folder sharing support pending invites for emails that do not yet have WyzQuests accounts? — Still open. Invites require an existing account.


11. OUT OF SCOPE

  • Permission level inheritance of parent -> child. — Implemented (v2.0). See the hierarchy rules in User Flows.

  • Deeper permission level logic for view and edit beyond current CRUD validation. — Partially addressed (v2.0): the permission matrix and hierarchy rules are implemented; per-item (non-folder) sharing is still out of scope.

  • Pending invitation workflow for non-existing users.

  • Bulk folder sharing.

  • Public folder sharing.

  • Cross-organization sharing. — Supported at folder level by design: any existing WyzQuests account can be invited. Organization-level sharing policies or controls are not implemented.


12. SUCCESS METRICS

  • List of all user accounts with specified permission level.

  • Creator or Agency Admin can add folder permissions.

  • Creator or Agency Admin can update folder permissions.

  • Creator or Agency Admin can revoke folder permissions.

  • Unauthorized users cannot manage folder permissions.

  • Folder owners retain authority over their whole folder tree, including subfolders created by collaborators.

  • Users demoted to Viewer are capped to view access for the entire subtree.

  • Only the folder owner and admins can manage permissions; the Admin role is limited to grants by the root tree owner.

  • Collaborators can preview shared content without altering it and create independent template copies.


18. DEPENDENCIES

This feature depends on

  • Supabase Auth (migrated from Clerk; completed September 2026).

  • Agency Admin, Creator, and User Account details.

  • Supabase Database.

  • Supabase RPC get_folder_ancestors (folder ancestor-chain resolution).

  • Project Folders.

  • Quest Folders.

  • Adventure Folders.

  • Email Service.

This feature depends on this

  • Agency Creation.

  • Content Library.

  • Folder Creation.

  • Folder Navigation.

  • Folder Permission Email Notification.


19. TIMELINE & OWNERSHIP

  • Backend: James Derick Billate (v1.0) — core-logic overhaul by Christian Denzon (v2.0).

  • Frontend: James Derick Billate (v1.0) — core-logic overhaul by Christian Denzon (v2.0).

  • QA: Internal development testing.

  • Estimated Completion: Feature completed (v2.0 overhaul merged and deployed August – September 2026).


Note: API Endpoints and Schema — please refer to its Internal Technical Guide (Manage Folder Permissions & Sharing).

Document version: 2.0 — Hand-off updated for the core-logic overhaul (hierarchy inheritance, permission management matrix, RLS hardening, shared preview + Use as Template, agency unification), September 30, 2026. PRs: #745, #763, #774, #782.


Was this article helpful?