♻️ Make /docs:sync-docs window days-based by default

docs/plugin-catalog/docs-plugin.md

@@ -6,7 +6,7 @@
 
 **Author:** Flop (flopspm@gmail.com)
 
-**Version:** 1.1.1
+**Version:** 1.2.0
 
 **Keywords:** documentation, sync, git, automation
 
@@ -105,28 +105,35 @@ yes
 
 ## Sync Documentation
 
-**Command:** `/docs:sync-docs [number_of_commits]`
+**Command:** `/docs:sync-docs [days | N commits]`
 
-Analyzes recent git commits and updates documentation to reflect code changes.
+Analyzes recent git changes and updates documentation to reflect code changes. The lookback window is measured in **days by default**; commit-count mode is opt-in via the explicit `commits` keyword.
 
 ### Usage
 
 ```bash
-# Analyze last 5 commits (default)
+# Analyze the last 1 day (default)
 /docs:sync-docs
 
-# Analyze specific number of commits
-/docs:sync-docs 10
-/docs:sync-docs 20
+# Analyze a specific number of days (bare number = days)
+/docs:sync-docs 3
+/docs:sync-docs 7
+
+# Analyze a specific number of commits (explicit `commits` keyword)
+/docs:sync-docs 10 commits
+/docs:sync-docs 1 commit
 ```
 
 ### Parameters
 
-- `number_of_commits` (optional): Number of recent commits to analyze. Default: 5
+- `days` (optional, default): A bare number is interpreted as a number of days to look back. Default: **1 day** when no argument is given.
+- `N commits` (optional): A number followed by the `commits` (or `commit`) keyword switches to commit-count mode and analyzes exactly that many commits.
+
+If the resolved window contains no commits (e.g., an empty time range in days mode, or an invalid window), the command reports `"no commits in the last N days, nothing to sync"` and makes no changes.
 
 ### What it does
 
-1. Extracts the specified number of recent commits from git history
+1. Parses the argument to resolve the lookback window — days by default, or a commit count when the `commits` keyword is used
 2. Analyzes commit messages and full diffs to understand changes
 3. Reads the current state of all modified files
 4. Identifies the documentation folder automatically
@@ -148,12 +155,12 @@ git commit -m "Add authentication middleware"
 git commit -m "Update API endpoints"
 git commit -m "Refactor database connection"
 
-# Sync documentation with the last 3 commits
+# Sync documentation with the last 3 days of changes
 /docs:sync-docs 3
 
 # Claude analyzes changes and updates relevant docs
 # Example output:
-# "Updated documentation based on 3 recent commits:
+# "Updated documentation based on commits from the last 3 days:
 #  - api-reference.md: Added new /auth endpoints
 #  - architecture.md: Updated authentication flow diagram
 #  - getting-started.md: Added authentication setup steps"
@@ -162,7 +169,7 @@ git commit -m "Refactor database connection"
 ### Best Practices
 
 - Run after completing a feature or significant change
-- Use higher commit counts (10-20) for major refactors
+- Use a wider window (e.g. `7` days, or `20 commits`) for major refactors
 - Review the changes to ensure accuracy
 - Combine with regular code reviews
 - Set up as a pre-release checklist item
@@ -197,13 +204,13 @@ The sync command thoroughly checks:
 
 1. **Initial Setup:** Use `/docs:generate-docs` to create documentation structure
 2. **Continuous Sync:** Use `/docs:sync-docs` regularly during development
-3. **Pre-Release:** Run `/docs:sync-docs 20` before releases to catch all changes
+3. **Pre-Release:** Run a wider window (e.g. `/docs:sync-docs 7` or `/docs:sync-docs 50 commits`) before releases to catch all changes
 4. **After Merges:** Sync after merging feature branches to update docs
 
 ### Performance Optimization
 
-- Use lower commit counts (3-5) for quick daily syncs
-- Use higher commit counts (10-20) for comprehensive pre-release checks
+- Use a short window (the default `1` day, or `3`) for quick daily syncs
+- Use a wider window (e.g. `7` days, or `20-50 commits`) for comprehensive pre-release checks
 - Run generate-docs once, then rely on sync-docs for updates
 
 ### Integration Ideas

plugins/docs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "docs",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Generate and keep documentation in sync with your codebase",
   "homepage": "https://github.com/Flopsstuff/flugins",
   "author": {

plugins/docs/commands/sync-docs.md

@@ -6,34 +6,45 @@ disable-model-invocation: false
 
 # Sync Documentation with Recent Changes
 
-Usage: `/docs:sync-docs [number_of_commits]`
+Usage: `/docs:sync-docs [days | N commits]`
 
-Analyze recent {number_of_commits} and update documentation to match current codebase:
+Analyze recent changes and update documentation to match current codebase:
 
-1. Extract the {number_of_commits} from the command arguments:
-   - If a {number_of_commits} is provided, use that value (e.g., `/docs:sync-docs 10` → analyze 10 commits)
-   - If no {number_of_commits} is provided, use 5 as default (e.g., `/docs:sync-docs` → analyze 5 commits)
+1. Parse `$ARGUMENTS` to determine the lookback window. The window is measured in **days by default**:
+   - **No argument** (e.g., `/docs:sync-docs`) → **days mode**, default **1 day** (look back 1 day).
+   - **A bare number** (e.g., `/docs:sync-docs 3`) → **days mode**, look back that many days (3 days).
+   - **A number followed by the `commits` keyword** (e.g., `/docs:sync-docs 10 commits`) → **commits mode**, analyze exactly that many commits (10 commits). Commits mode is selected ONLY when the explicit `commits` (or `commit`) keyword follows the number.
+   - Examples:
+     - `/docs:sync-docs` → last 1 day (days mode)
+     - `/docs:sync-docs 7` → last 7 days (days mode)
+     - `/docs:sync-docs 10 commits` → last 10 commits (commits mode)
+     - `/docs:sync-docs 1 commit` → last 1 commit (commits mode)
 
-2. Analyze recent commits to understand changes:
-   - Use `git log -N -p` to get full commit history with diffs (where N is the number of commits)
-   - Review commit messages and full diff to understand the context of changes
-   - Use `git log -N --name-only` to list all files changed in these commits
-   - **IMPORTANT**: Read the CURRENT state of all changed files from the repository to understand the actual implementation
+2. Build the git commands based on the parsed window:
+   - **Days mode** (N days): use `git log --since="N days ago" -p` to get full diffs and `git log --since="N days ago" --name-only` to list changed files.
+   - **Commits mode** (N commits): use `git log -N -p` to get full diffs and `git log -N --name-only` to list changed files.
 
-3. Read all modified files from recent commits:
-   - For each file changed in the analyzed commits, read its CURRENT content
+3. Analyze the commits in the window to understand changes:
+   - Run the `-p` command from step 2 to get full commit history with diffs.
+   - Review commit messages and full diffs to understand the context of changes.
+   - Run the `--name-only` command from step 2 to list all files changed in the window.
+   - **Empty-window guard**: If the git log returns no commits (e.g., an empty time window in days mode, or an invalid/zero window), stop here. Report `"no commits in the last N days, nothing to sync"` (substituting the resolved window) and do nothing destructive — make no documentation edits.
+   - **IMPORTANT**: Read the CURRENT state of all changed files from the repository to understand the actual implementation.
+
+4. Read all modified files from the analyzed commits:
+   - For each file changed in the window, read its CURRENT content
    - Pay special attention to:
      - New files added (understand their purpose and functionality)
      - Modified files (understand what changed and why)
      - Deleted files (ensure they're not referenced in docs)
    - Analyze code to understand features, APIs, configuration, and architecture
 
-4. Find and scan the documentation folder:
+5. Find and scan the documentation folder:
    - Search for common documentation folder names in the project root: `docs/`, `doc/`, `documentation/`
    - Check for documentation indicators in README.md or project config files
    - Once the documentation folder is identified, scan it to identify all documentation files
 
-5. Compare the documentation content with actual codebase state:
+6. Compare the documentation content with actual codebase state:
    - Match documentation against CURRENT file contents (not just diffs)
    - Understand the full context of changes by reading actual code
    - Identify inconsistencies between docs and code:
@@ -44,13 +55,13 @@ Analyze recent {number_of_commits} and update documentation to match current cod
      - Broken links to non-existent files
      - Configuration changes not reflected
 
-6. Update all affected documentation files to match current state:
+7. Update all affected documentation files to match current state:
    - Base updates on ACTUAL current file contents
    - Ensure code examples reflect real implementation
    - Update API signatures, parameters, and return values
    - Fix broken references and links
 
-7. Maintain documentation structure:
+8. Maintain documentation structure:
    - **Root index.md**: Ensure there's an `index.md` in the docs root folder
      - Contains links to ALL files and folders at that level
      - Each link has a short description of content
@@ -64,7 +75,7 @@ Analyze recent {number_of_commits} and update documentation to match current cod
      - Keep structure flat when possible for better navigation
    - **Update index files**: When adding/modifying docs, always update relevant `index.md` files
 
-8. Provide short summary of all changes made
+9. Provide short summary of all changes made
 
 Be thorough and check: