docs: add profile workflow documentation to README and website (closes #42)

Author: serkanyersen

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- **Docs**: Add profile workflow documentation to README and website (closes #42)
+
 ---
 
 ## [0.3.0] - 2026-02-05

README.md

@@ -207,6 +207,59 @@ Then add `fpath=(~/.zsh/completions $fpath)` to your .zshrc before your framewor
 4. **Common Files**: Files that are shared across all profiles are stored in the `common` section and linked regardless of the active profile
 5. **Sync**: Changes are committed and synced with GitHub automatically
 
+## Working with Profiles
+
+Profiles are how DotState organizes your dotfiles for different machines or contexts. Each profile has its own set of files, while **Common Files** are shared across all profiles automatically.
+
+```
+               ┌────────────────────┐
+               │ Common Files       │
+               ├────────────────────┤
+               │ .tmux.conf         │
+               │ .gitconfig         │       ┌────────────────────┐
+               │ .vimrc             │       │ Server             │
+               │                    │       ├────────────────────┤
+               │                    ├──────►│ .bashrc            │
+               │                    │       │ .profile           │
+               └─┬─────────────────┬┘       │ .config.toml       │
+                 │                 │        └────────────────────┘
+                 │                 │
+                 ▼                 ▼
+┌────────────────────┐           ┌────────────────────┐
+│ Personal           │           │ Work               │
+├────────────────────┤           ├────────────────────┤
+│ .zshrc             │           │ .zshrc             │
+│ .sshconfig         │  Copy     │ .sshconfig         │
+│ ...                ├──────────►│ ...                │
+│                    │           │ workfile.sh        │
+└────────────────────┘           └────────────────────┘
+```
+
+### Creating Profiles
+
+In the TUI, go to **Manage Profiles** and press `C` to create a new profile. You can:
+
+- **Start blank** for a completely new setup
+- **Copy from an existing profile** to carry over files and packages — great for setting up a similar machine quickly
+
+### Switching Profiles
+
+Select a profile and press `Enter` to switch. DotState will remove symlinks for the old profile and create symlinks for the new one automatically. Common files stay linked regardless of which profile is active.
+
+### Common Files
+
+You decide which files are shared. Move any file to **Common** and it will be symlinked in every profile. Common files stay linked when you switch profiles. To move a file between profile-specific and common:
+
+1. Go to **Manage Files**
+2. Select a file
+3. Press `M` to move it to Common (or back to the active profile)
+
+### Use Cases
+
+- **Multi-machine**: Use a `Personal` profile on your laptop, `Work` on your work machine, and `Server` for headless setups. Keep shared configs (`.gitconfig`, `.tmux.conf`) in Common.
+- **Same computer, different contexts**: Create profiles like `day`, `night`, or `focus` with different terminal themes and defaults, and switch between them instantly.
+- **Quick duplication**: When setting up a second machine, create a new profile by copying from an existing one, then tweak what's different.
+
 ## Configuration
 
 ### Repository Setup Modes

website/.gitignore

@@ -20,3 +20,4 @@ npm-debug.log*
 
 # OS files
 .DS_Store
+.vercel

website/public/screenshot.png

@@ -76,6 +76,8 @@ const sections = [
                     <div class="section-content">
                         <p><strong>DotState</strong> is a terminal-based <strong>dotfile manager</strong> that helps you manage your dotfiles effortlessly. Whether you're syncing your configuration across multiple machines or setting up a new development environment, DotState makes it simple, safe, and fast.</p>
 
+                        <img src="/screenshot.png" alt="DotState TUI screenshot showing the main menu with Tokyo Night dark theme" class="screenshot" width="1130" height="868" loading="eager" />
+
                         <InstallWidget />
 
                         <h3>Why Use a Dotfile Manager?</h3>
@@ -122,6 +124,10 @@ const sections = [
                         <Tip>
                             <strong>Tip:</strong> When you select a file, it's automatically copied to your repository and a symlink is created in its place. This means your files are safely backed up and version controlled.
                         </Tip>
+
+                        <h3>Profiles & Common Files</h3>
+                        <p>Organize your dotfiles with <strong>profiles</strong> for different machines or contexts. Files you choose to mark as <strong>common</strong> are shared across all profiles — the rest stay profile-specific. See <a href="#examples" class="section-link" data-section="examples">Examples</a> for workflows.</p>
+                        <CodeBlock code={"Common Files (shared)     Profile-specific\n─────────────────────    ─────────────────\n .gitconfig               Personal/\n .tmux.conf      ───►      .zshrc\n .vimrc                    .ssh/config\n                          Work/\n                           .zshrc\n                           work-scripts/"} />
                     </div>
 
                     <StatusGrid />
@@ -400,20 +406,28 @@ const sections = [
                         </ExampleCard>
 
                         <ExampleCard title="Managing multiple profiles">
-                            <p>Create separate profiles for different contexts:</p>
+                            <p>Profiles let you organize dotfiles for different machines or contexts. Each profile has its own files, while <strong>Common Files</strong> are shared across all profiles.</p>
+                            <ul>
+                                <li><strong>Create a profile:</strong> Press <kbd>C</kbd> in Manage Profiles</li>
+                                <li><strong>Copy from existing:</strong> When creating, choose an existing profile to start with — copies all files and packages</li>
+                                <li><strong>Switch profiles:</strong> Select a profile and press <kbd>Enter</kbd> — symlinks are swapped automatically</li>
+                            </ul>
+                            <p><strong>Example setups:</strong></p>
                             <ul>
-                                <li><strong>Personal:</strong> Your personal dotfiles</li>
-                                <li><strong>Work:</strong> Work-specific configurations</li>
-                                <li><strong>Mac/Linux:</strong> OS-specific settings</li>
+                                <li><strong>Multi-machine:</strong> <code>Personal</code> on your laptop, <code>Work</code> on your work machine, <code>Server</code> for headless setups</li>
+                                <li><strong>Same computer:</strong> <code>day</code>, <code>night</code>, or <code>focus</code> profiles with different terminal themes</li>
                             </ul>
                         </ExampleCard>
 
                         <ExampleCard title="Sharing common files">
+                            <p>You decide which files are shared. Move any file to <strong>Common</strong> and it will be symlinked in every profile. Files stay in Common when you switch profiles.</p>
                             <ol>
-                                <li>Add a file like <code>.gitconfig</code> to your collection</li>
-                                <li>Move it to the <strong>Common</strong> section</li>
-                                <li>The file will now be symlinked in every profile</li>
+                                <li>Go to <strong>Manage Files</strong></li>
+                                <li>Select a file from your profile</li>
+                                <li>Press <kbd>M</kbd> to move it to Common</li>
                             </ol>
+                            <p>Press <kbd>M</kbd> again on a common file to move it back to the active profile.</p>
+                            <CodeBlock code={"Common Files (you choose)   Profiles (per-machine)\n─────────────────────────  ──────────────────────\n .gitconfig       ┌──────► Personal/.zshrc\n .tmux.conf  ─────┤        Personal/.ssh/config\n .vimrc           └──────► Work/.zshrc\n                           Work/work-scripts/"} />
                         </ExampleCard>
                     </div>
                 </article>
@@ -794,6 +808,11 @@ const sections = [
 </Layout>
 
 <style>
+    .screenshot {
+        width: 100%;
+        height: auto;
+    }
+
     .requirements-list {
         list-style: none;
         margin-left: 0;