docs(runbooks): piege ACL Synology mcp-nas root namespace vs ssh nas-host

common/mcp-nas-acl-synology-claude-staging-20260902.md

@@ -0,0 +1,24 @@
+# mcp-nas : root conteneur bloqué par ACL Synology sur certains dossiers .claude-staging — passer par ssh nas-host
+
+**Date** : 2026-09-02
+**Contexte** : revue visuelle du showcase `nyora-convert-api` (ticket nyora-2026-09-004), recherche des PNG générés par `/render-preview` dans `/volume1/docker/.claude-staging/pack-mp1-test/`.
+
+## Symptôme
+
+Depuis mcp-nas (`find` / `ls` sur `/mnt/docker/.claude-staging/pack-mp1-test/...`), le dossier apparaît vide ou renvoie `Permission denied` — alors que le même chemin, exploré via `ssh nas-host` (compte `claude-ops`), liste bien tout le contenu attendu (PDF, JSON, `verified.md`, PNG de rendu).
+
+## Cause
+
+mcp-nas tourne en `root` (uid=0) mais dans un namespace conteneur — ce root n'est **pas** le root réel du host Synology. Sur ce NAS, certains dossiers (ex. `pack-mp1-test`, `drwxrws---`, propriétaire uid 1040/`claude-ops`, groupe `users`) sont protégés par des ACL Synology qui se superposent aux bits POSIX classiques. Le root namespacé de mcp-nas n'a aucun passe-droit sur ces ACL, contrairement à `ssh nas-host` qui s'authentifie comme le vrai compte `claude-ops` (uid=1040, groupes users/administrators/docker) et hérite de ses droits normaux.
+
+`docker exec <container> id` depuis mcp-nas confirme le namespace : à l'intérieur d'un container applicatif (ex. `nyora-convert-api`), l'utilisateur `appuser` (uid=1026, gid=100/users) lit sans problème le même dossier via son propre bind-mount — la restriction est bien spécifique à l'accès direct de mcp-nas au chemin hôte, pas au dossier lui-même.
+
+## Règle appliquée
+
+Pour tout accès à `/volume1/docker/.claude-staging/**` (ou tout dossier avec permissions restrictives `rws---`/`rwx---` similaires) : ne pas se fier à un `find`/`ls` vide ou en erreur depuis mcp-nas pour conclure à l'absence de fichiers. Toujours revérifier via `ssh nas-host "find ..."` (ou `docker exec <container-propriétaire> find ...`) avant de conclure. `docker` lui-même n'est pas dans le PATH de mcp-nas ni de la session SSH par défaut : utiliser le chemin complet `/usr/local/bin/docker`.
+
+## Application
+
+A permis de retrouver les 87 pages PNG + le dossier `thumbs/` (10 vignettes JPG réduites) générés par `render_preview.py`, invisibles depuis mcp-nas seul, débloquant la revue visuelle du showcase.
+
+**Tags** : infra, mcp-nas, acl, synology, permissions, ssh, claude-staging, piege