Hidden Directories Guide - Managing Private Content in Sasha Studio

Generated: 2025-01-12 UTC
Purpose: Guide to managing hidden directories and private content in the Sasha documentation system
Reference: See docker-documentation-deployment-plan.md for full implementation details

What Are Hidden Directories?

Hidden directories (and files) in Unix/Linux systems are those whose names begin with a dot (.). This is a convention that dates back to the early days of Unix, where it was initially a bug that became a feature.

Examples of Hidden Directories

.config/        # Application configurations
.cache/         # Cached data
.local/         # User-specific data
.ssh/           # SSH keys and config
.git/           # Git repository data
.private/       # Private/sensitive files
.can-you-see-me/  # Custom hidden directory

Why Use Hidden Directories?

Common Use Cases

Configuration Files
- Keep settings separate from regular files
- Prevent accidental deletion
- Reduce visual clutter
System Files
- Version control (.git)
- Build artifacts (.next, .vite)
- Dependencies (.npm)
Security Through Obscurity
- Not true security, but reduces casual browsing
- Hides sensitive configuration
- Keeps private data less visible
Organization
- Separates metadata from content
- Keeps working directories clean
- Groups related system files

Working with Hidden Directories

Viewing Hidden Directories

1. Using `ls` Command

# Show hidden files/directories
ls -a

# Show hidden files with details
ls -la

# Show only hidden files/directories
ls -ld .*

# Show hidden directories only
ls -d .*/

2. Using `find` Command

# Find all hidden directories
find . -type d -name ".*"

# Find hidden directories, exclude .git
find . -type d -name ".*" ! -name ".git"

# Find hidden directories at specific depth
find . -maxdepth 1 -type d -name ".*"

# Find hidden directories excluding node_modules
find . -type d -name ".*" ! -path "*/node_modules/*"

3. File Managers

GUI: Most file managers have "Show Hidden Files" option (Ctrl+H)
Terminal: tree -a shows directory tree including hidden

Creating Hidden Directories

# Create a hidden directory
mkdir .secret-folder

# Create nested hidden directory
mkdir -p .config/app/settings

# Create with specific permissions
mkdir -m 700 .private  # Only owner can access

Navigating Hidden Directories

# Change to hidden directory
cd .hidden-folder

# List contents of hidden directory
ls .hidden-folder/

# Copy files to hidden directory
cp file.txt .private/

# Move files from hidden directory
mv .temp/* ./

Security Considerations

Important: Hidden ≠ Secure

Hidden directories are NOT a security mechanism. They are:

Good for organization
Good for reducing clutter
NOT for securing sensitive data
NOT encryption

Actual Security Measures

# Set restrictive permissions
chmod 700 .private  # Only owner can read/write/execute
chmod 600 .private/secret.txt  # Only owner can read/write

# Encrypt sensitive data
gpg -c sensitive.txt  # Creates encrypted sensitive.txt.gpg

# Use proper access controls
# Consider using:
# - File system encryption
# - Proper user permissions
# - ACLs (Access Control Lists)

Common Hidden Directories

System Level

Directory	Purpose
`.git/`	Git version control data
`.github/`	GitHub workflows and configs
`.vscode/`	VS Code workspace settings
`.idea/`	IntelliJ IDEA project files
`.npm/`	NPM cache and config
`.docker/`	Docker configuration

User Home Directory

Directory	Purpose
`~/.ssh/`	SSH keys and known hosts
`~/.config/`	Application configurations
`~/.cache/`	Application caches
`~/.local/`	User-specific data
`~/.bash_history`	Bash command history

Project Level

Directory	Purpose
`.env`	Environment variables
`.gitignore`	Git ignore rules
`.dockerignore`	Docker ignore rules
`.next/`	Next.js build output
`.vite/`	Vite build cache

Troubleshooting Hidden Directories

Issue 1: Can't See Hidden Directories

Problem: ls doesn't show hidden directories

Solutions:

# Use -a flag
ls -a

# Check if filtered by shell
echo .*  # Should show hidden items

# Check aliases
alias ls  # See if ls is aliased without -a

Issue 2: Wildcards Not Matching

Problem: ls .* or find .* not working as expected

Solutions:

# Use explicit patterns
ls -d .*/

# Use find instead
find . -maxdepth 1 -name ".*" -type d

# Escape the dot
ls -d \.*

Issue 3: Permission Denied

Problem: Can't access hidden directory

Solutions:

# Check permissions
ls -ld .private/

# Fix permissions (if owner)
chmod 755 .private/

# Check ownership
ls -ld .private/ | awk '{print $3, $4}'

Best Practices

1. Naming Conventions

# Good hidden directory names
.config/        # Clear purpose
.cache/         # Obvious use
.private/       # Indicates sensitivity
.backup/        # Clear function

# Avoid
.a/            # Too vague
.temp123/      # Unclear purpose
..hidden/      # Confusing (starts with ..)

2. Documentation

Always document hidden directories in your project:

## Hidden Directories
- `.config/` - Application configuration files
- `.private/` - Sensitive data (git-ignored)
- `.cache/` - Temporary cache files

3. Git Considerations

# Add to .gitignore if sensitive
echo ".private/" >> .gitignore
echo ".env" >> .gitignore

# Force add hidden file to git
git add -f .important-config

# Check what's ignored
git status --ignored

Finding Hidden Secrets Exercise

Based on the Sasha project example, here's how to systematically search for hidden content:

# 1. Find all hidden directories
find . -type d -name ".*" ! -path "*/.git/*" ! -path "*/node_modules/*"

# 2. List contents of each hidden directory
for dir in $(find . -type d -name ".*" ! -path "*/.git/*"); do
    echo "=== $dir ==="
    ls -la "$dir" 2>/dev/null
done

# 3. Search for specific files in hidden directories
find . -path "*/.*" -name "secret*" -type f

# 4. Check recently modified hidden files
find . -path "*/.*" -type f -mtime -7  # Modified in last 7 days

# 5. Search content in hidden directories
grep -r "secret\|password\|key" .*/  2>/dev/null

Creating Your Own Hidden Directory Challenge

Want to create a hidden directory challenge like the one in this project?

# Create hidden directory with secret
mkdir -p docs/.can-you-see-me
echo 'The secret is "YourSecretHere"' > docs/.can-you-see-me/secret.md

# Set permissions (optional)
chmod 755 docs/.can-you-see-me
chmod 644 docs/.can-you-see-me/secret.md

# Create decoy directories
mkdir -p docs/.private
mkdir -p docs/.cache
touch docs/.cache/empty

# Create README hint
echo "Can you find the hidden secret in the docs?" >> README.md

Implementation in Docker Deployment

Dockerfile Configuration

# Dockerfile.sliplane excerpt
FROM node:20-alpine AS docs-builder

# Copy documentation sources
COPY docs-deploy/ ./docs-deploy/

# In main stage, copy with hidden directories preserved
COPY --from=docs-builder /docs-build/docs-deploy/ /app/workspaces/workspace/docs/

# Ensure hidden directories maintain proper permissions
RUN chmod 755 /app/workspaces/workspace/docs/.private || true

Server-Side Filtering

// server/index.js - File browser endpoint
app.get('/api/workspace/files', async (req, res) => {
    const files = await fsPromises.readdir(docsPath);
    
    // Filter out hidden directories from UI
    const visibleFiles = files.filter(file => !file.startsWith('.'));
    
    res.json({ files: visibleFiles });
});

Claude CLI Access Pattern

// Claude CLI can bypass UI filtering
// When claude command runs in container:
const allFiles = fs.readdirSync('/app/workspaces/workspace/docs/');
// Returns: ['getting-started', 'specialists', 'guides', '.private', '.can-you-see-me']

// UI file browser only sees:
const uiFiles = allFiles.filter(f => !f.startsWith('.'));
// Returns: ['getting-started', 'specialists', 'guides']

Summary: Private Content Management in Sasha

Architecture Overview

The Sasha documentation system uses a three-tier visibility model:

Public Content (~62 docs): Visible in UI and CLI
Hidden Content: Accessible only via Claude CLI
Development Content: Stays local, not deployed

Key Implementation Points

Hidden Directory Convention

Directories starting with . are filtered from UI
Claude CLI can access all directories including hidden
Perfect for proprietary methodologies and IP

Docker Deployment Structure

/app/workspaces/workspace/docs/
├── getting-started/     # Public
├── specialists/         # Public
├── guides/             # Public
└── .private/           # Hidden (CLI-only)

Security Layers

Unix convention (. prefix)
Application filtering (UI level)
Container isolation (Docker)
Access verification testing

Content Categories

Deploy: User guides, templates, tutorials
Hide: Proprietary methods, strategies, advanced prompts
Keep Local: Technical specs, planning docs, research

Verification Commands

# Check UI cannot see hidden content
curl http://localhost:3005/api/files/list | grep "\.private"
# Should return nothing

# Verify Claude CLI access
docker exec sasha-container claude --print "ls docs/.private/"
# Should list hidden files

The Kerikeri Secret

As demonstrated in this project, the hidden directory .can-you-see-me/ contains a secret ("Kerikeri") that's invisible to the UI but accessible to Claude CLI - proving the system works as designed for protecting proprietary content while maintaining operational access.

Implementation Status: This private content management system is actively deployed in Sasha Studio containers, providing a secure way to include proprietary methodologies in deployments while keeping them hidden from end users.

Hidden Directories Guide - Managing Private Content in Sasha Studio

What Are Hidden Directories?

Examples of Hidden Directories

Why Use Hidden Directories?

Common Use Cases

Working with Hidden Directories

Viewing Hidden Directories

1. Using ls Command

2. Using find Command

3. File Managers

Creating Hidden Directories

Navigating Hidden Directories

Security Considerations

Important: Hidden ≠ Secure

Actual Security Measures

Common Hidden Directories

System Level

User Home Directory

Project Level

Troubleshooting Hidden Directories

Issue 1: Can't See Hidden Directories

Issue 2: Wildcards Not Matching

Issue 3: Permission Denied

Best Practices

1. Naming Conventions

2. Documentation

3. Git Considerations

Finding Hidden Secrets Exercise

Creating Your Own Hidden Directory Challenge

Implementation in Docker Deployment

Dockerfile Configuration

Server-Side Filtering

Claude CLI Access Pattern

Summary: Private Content Management in Sasha

Architecture Overview

Key Implementation Points

Verification Commands

The Kerikeri Secret

1. Using `ls` Command

2. Using `find` Command