Clarify ItemTag policy uses Shop permissions (no separate ItemTag perms)

Author: dadachi

docs/nativeapptemplate-substrate-v2-overview.md

@@ -103,7 +103,7 @@ Shopkeeper (user)
 - `invitation`
 - `read_data`
 
-**Role → Permission mapping (Notion-style, member can create)**:
+**Role → Permission mapping (collaborative SaaS model, Notion-style)**:
 
 | Permission | admin | member |
 |---|---|---|
@@ -114,6 +114,12 @@ Shopkeeper (user)
 | invitation | ✓ | |
 | read_data | ✓ | ✓ |
 
+**ItemTag access** (no separate permissions — uses Shop permissions):
+- `read_data` → index, show item_tags
+- `update_shops` → create, update, destroy, state toggle item_tags
+
+See section 6.10 for rationale on the unified permission approach.
+
 #### Version enforcement (preserved)
 
 - `AppVersion`, `PrivacyVersion`, `TermsVersion` — unchanged
@@ -421,6 +427,31 @@ The agent can rename identifiers but cannot rewrite arbitrary string literals wi
 - Reduces context-switching cost
 - Allows iOS validation to inform Android design decisions
 
+### 6.10 Why no separate ItemTag permissions
+
+ItemTag is a child of Shop. Modern collaborative SaaS (Notion, Linear, Trello) treat parent-level permissions as implicitly applying to children. Adding separate ItemTag permissions would:
+
+- Double the permission count (shop-level + item-tag-level)
+- Complicate the role-permission matrix for a 2-tier role system
+- Be overkill given that admin and member have nearly identical capabilities in this design
+
+The policy file resolves ItemTag operations to Shop permissions:
+- `read_data` → index, show
+- `update_shops` → create, update, destroy, state toggle
+
+This matches "collaborative SaaS" model (Notion/Linear/Trello-style): both admin and member can freely CRUD resources; admin's only extra capability is team management (invitation, organization settings).
+
+If a future agent-generated domain requires operational separation (e.g., clinic staff can toggle item state but only admin can create items), a new `toggle_item_tags` permission can be introduced alongside a third role tier at that time. For now, keeping permissions minimal is aligned with YAGNI.
+
+### 6.11 Why admin and member can both create and modify resources
+
+An alternative design (operational SaaS model) would restrict resource creation or state changes to admin only. We chose the collaborative model because:
+
+- ~90% of agent-generatable domains (task trackers, shopping lists, reading lists, bookmark managers, recipe collections, habit trackers) are collaborative by nature
+- The operational model (clinic waitlist, factory inventory, restaurant service) is a specialized case
+- In collaborative apps, "member" implies peer collaborator, not restricted user
+- If a domain needs the operational model later, a third role tier (`viewer` or `staff`) can be added
+
 ---
 
 ## 7. Rollback Strategy

docs/phase1-rails-api.md

@@ -467,14 +467,56 @@ git commit -m "Update serializers for new ItemTag schema"
 
 ### 10.1 Edit `app/policies/api/shopkeeper/item_tag_policy.rb`
 
-Remove permission checks referencing deleted permission tags:
-- `manage_tags`, `write_info_to_tags`, `reset_all_tags`, `complete_or_reset_tags`, `show_tag_info`
+ItemTag is a child resource of Shop. In this substrate, there are no separate ItemTag permissions — ItemTag operations are authorized via Shop permissions. This matches modern collaborative SaaS (Notion, Linear, Trello) where parent permissions implicitly apply to children.
 
-Replace with generic permission checks:
-- `create_shops` (if treating ItemTag as Shop-scoped)
-- `update_shops`, `delete_shops`, `read_data`
+Mapping:
+- `read_data` → index, show
+- `update_shops` → create, update, destroy, state toggle (complete/idle)
 
-Actual mapping depends on the role redesign in Step 12. Initial simpler version: all authenticated shopkeepers can CRUD item_tags within their own account (via `acts_as_tenant` scoping).
+Expected policy:
+
+```ruby
+class Api::Shopkeeper::ItemTagPolicy < Api::Shopkeeper::BasePolicy
+  def index?
+    shopkeeper.has_permission?("read_data")
+  end
+
+  def show?
+    shopkeeper.has_permission?("read_data")
+  end
+
+  def create?
+    shopkeeper.has_permission?("update_shops")
+  end
+
+  def update?
+    shopkeeper.has_permission?("update_shops")
+  end
+
+  def destroy?
+    shopkeeper.has_permission?("update_shops")
+  end
+
+  # State toggle actions (if the controller has complete / idle custom actions)
+  def complete?
+    shopkeeper.has_permission?("update_shops")
+  end
+
+  def idle?
+    shopkeeper.has_permission?("update_shops")
+  end
+end
+```
+
+(Adjust method names to match the actual controller actions and base policy class structure.)
+
+Also check other policies for references to removed permission tags and replace with the new permission set:
+
+```bash
+grep -rn "manage_tags\|write_info_to_tags\|reset_all_tags\|complete_or_reset_tags\|show_tag_info" app/policies/
+```
+
+Any match must be replaced with `update_shops` or `read_data` as appropriate, or the method removed if it was queue-specific.
 
 ### 10.2 Verify
 
@@ -487,7 +529,7 @@ grep -rn "manage_tags\|write_info_to_tags\|reset_all_tags\|complete_or_reset_tag
 
 ```bash
 git add app/policies/
-git commit -m "Update ItemTag policy: remove queue-specific permission checks"
+git commit -m "Update ItemTag policy: use Shop permissions (read_data, update_shops)"
 ```
 
 ---