refactor: reorganize repository structure

- Move design docs to docs/
- Move packaging files to packaging/
- Create GitHub issues and milestones for tracking
- Update workflow and README references

.claude/settings.local.json

@@ -20,7 +20,15 @@
       "Bash(/Users/james.maes/Git.Local/QRunIO/qctl/qctl-core/target/qctl:*)",
       "Bash(gh run list:*)",
       "Bash(gh run view:*)",
-      "Bash(JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-21.jdk/Contents/Home mvn spotless:apply:*)"
+      "Bash(JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-21.jdk/Contents/Home mvn spotless:apply:*)",
+      "Bash(mkdir:*)",
+      "Bash(mv:*)",
+      "Bash(gh label list:*)",
+      "Bash(gh repo view:*)",
+      "Bash(gh issue create:*)",
+      "Bash(gh issue list:*)",
+      "Bash(gh api:*)",
+      "Bash(gh issue edit:*)"
     ]
   }
 }

.github/workflows/build.yml

@@ -141,6 +141,7 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
+          file: packaging/docker/Dockerfile
           platforms: linux/amd64,linux/arm64
           push: true
           tags: |
@@ -176,25 +177,25 @@ jobs:
           SHA_WINDOWS=$(shasum -a 256 artifacts/qctl-windows-amd64.exe/qctl-windows-amd64.exe | cut -d' ' -f1)
 
           # Update Homebrew
-          sed -i "s/version \".*\"/version \"${VERSION}\"/" HomebrewFormula/qctl.rb
-          sed -i "s/PLACEHOLDER_ARM64_SHA256/${SHA_MACOS_ARM64}/" HomebrewFormula/qctl.rb
-          sed -i "s/PLACEHOLDER_AMD64_SHA256/${SHA_MACOS_AMD64}/" HomebrewFormula/qctl.rb
-          sed -i "s/PLACEHOLDER_LINUX_AMD64_SHA256/${SHA_LINUX_AMD64}/" HomebrewFormula/qctl.rb
-          sed -i "s/PLACEHOLDER_LINUX_ARM64_SHA256/${SHA_LINUX_ARM64}/" HomebrewFormula/qctl.rb
+          sed -i "s/version \".*\"/version \"${VERSION}\"/" packaging/homebrew/qctl.rb
+          sed -i "s/PLACEHOLDER_ARM64_SHA256/${SHA_MACOS_ARM64}/" packaging/homebrew/qctl.rb
+          sed -i "s/PLACEHOLDER_AMD64_SHA256/${SHA_MACOS_AMD64}/" packaging/homebrew/qctl.rb
+          sed -i "s/PLACEHOLDER_LINUX_AMD64_SHA256/${SHA_LINUX_AMD64}/" packaging/homebrew/qctl.rb
+          sed -i "s/PLACEHOLDER_LINUX_ARM64_SHA256/${SHA_LINUX_ARM64}/" packaging/homebrew/qctl.rb
 
           # Update Scoop
-          sed -i "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" scoop/qctl.json
-          sed -i "s|/v[0-9.]*\/|/v${VERSION}/|g" scoop/qctl.json
-          sed -i "s/PLACEHOLDER_WINDOWS_SHA256/${SHA_WINDOWS}/" scoop/qctl.json
+          sed -i "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" packaging/scoop/qctl.json
+          sed -i "s|/v[0-9.]*\/|/v${VERSION}/|g" packaging/scoop/qctl.json
+          sed -i "s/PLACEHOLDER_WINDOWS_SHA256/${SHA_WINDOWS}/" packaging/scoop/qctl.json
 
           # Update AUR
-          sed -i "s/pkgver=.*/pkgver=${VERSION}/" aur/PKGBUILD
-          sed -i "s/PLACEHOLDER_LINUX_SHA256/${SHA_LINUX_AMD64}/" aur/PKGBUILD
+          sed -i "s/pkgver=.*/pkgver=${VERSION}/" packaging/aur/PKGBUILD
+          sed -i "s/PLACEHOLDER_LINUX_SHA256/${SHA_LINUX_AMD64}/" packaging/aur/PKGBUILD
 
       - name: Commit package updates
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add HomebrewFormula/qctl.rb scoop/qctl.json aur/PKGBUILD
+          git add packaging/homebrew/qctl.rb packaging/scoop/qctl.json packaging/aur/PKGBUILD
           git commit -m "chore(packages): update manifests to ${GITHUB_REF_NAME}"
           git push

CLAUDE.md

@@ -34,14 +34,17 @@ JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-21.jdk/Contents/Home mvn cle
 ## Module Structure
 
 ```
-qctl-parent (reactor)
+qctl/
 ├── qctl-shared     # DTOs, ExitCodes, SPI interfaces, utilities
 ├── qctl-core       # Config, HTTP client, auth, cache, logging, Main entrypoint
 ├── qctl-qqq        # Template scaffolding (init, list) with Handlebars
 ├── qctl-qbit       # Package management commands, lockfile handling
 ├── qctl-qrun       # OCI packaging and deployment commands
 ├── qctl-qstudio    # AI planning commands (offline V1)
-└── qctl-cli        # Aggregator for native image build (only module with native profile)
+├── qctl-cli        # Aggregator for native image build (only module with native profile)
+├── docs/           # Architecture and design documentation
+├── packaging/      # Distribution manifests (Homebrew, Scoop, AUR, Docker)
+└── codestyle/      # Checkstyle config and license headers
 ```
 
 ## Architecture
@@ -93,10 +96,10 @@ On tagged release (`git tag v1.0.0 && git push origin v1.0.0`):
 
 | Channel | Location | Auto-Updated |
 |---------|----------|--------------|
-| Homebrew | `HomebrewFormula/qctl.rb` | Yes |
-| Scoop | `scoop/qctl.json` | Yes |
-| AUR | `aur/PKGBUILD` | Yes |
-| Docker | `ghcr.io/qrun-io/qctl` | Yes |
+| Homebrew | `packaging/homebrew/qctl.rb` | Yes |
+| Scoop | `packaging/scoop/qctl.json` | Yes |
+| AUR | `packaging/aur/PKGBUILD` | Yes |
+| Docker | `packaging/docker/Dockerfile` | Yes |
 | GitHub | Releases | Yes |
 
 **Platforms**: Linux (x64, ARM64), macOS (Intel, Apple Silicon), Windows (x64)

README.md

@@ -153,7 +153,10 @@ qctl/
 ├── qctl-qqq/       # Scaffolding commands (init, list)
 ├── qctl-qbit/      # Package management commands
 ├── qctl-qrun/      # Deployment commands
-└── qctl-qstudio/   # Planning commands
+├── qctl-qstudio/   # Planning commands
+├── docs/           # Architecture and design documentation
+├── packaging/      # Distribution manifests (Homebrew, Scoop, AUR, Docker)
+└── codestyle/      # Checkstyle config and license headers
 ```
 
 ## Development
@@ -190,10 +193,10 @@ This automatically:
 
 | Channel | Package | Auto-Updated |
 |---------|---------|--------------|
-| Homebrew | `HomebrewFormula/qctl.rb` | Yes |
-| Scoop | `scoop/qctl.json` | Yes |
-| AUR | `aur/PKGBUILD` | Yes |
-| Docker | `ghcr.io/qrun-io/qctl` | Yes |
+| Homebrew | `packaging/homebrew/qctl.rb` | Yes |
+| Scoop | `packaging/scoop/qctl.json` | Yes |
+| AUR | `packaging/aur/PKGBUILD` | Yes |
+| Docker | `packaging/docker/Dockerfile` | Yes |
 | GitHub | Releases page | Yes |
 
 ### Supported Platforms

TODO.md

@@ -1,130 +0,0 @@
-# TODO
-
-## Completed
-
-### Phase 1: Framework Cleanup
-- [x] Update dependencies to latest stable versions
-- [x] Add ExitCodes constants class in qctl-shared
-- [x] Update commands to use ExitCodes constants
-- [x] Fix SystemPaths.ensureDir() logging
-- [x] Remove duplicate Javadoc in JsonMerge.java
-- [x] Add Handlebars dependency to qctl-qqq
-
-### Phase 2: qqq init Command
-- [x] Create InitCommand with picocli structure
-- [x] Create TemplateResolver for git/local/github sources
-- [x] Create TemplateManifest parser
-- [x] Create TemplateEngine with Handlebars rendering
-- [x] Create PromptRunner for inquirer-style prompts
-- [x] Create PostGenHookRunner for executing hooks
-- [x] Create TemplatesHub to fetch templates.yaml from hub
-- [x] Create ListCommand to list available templates
-- [x] Fix Handlebars native image resource loading
-- [x] Remove native profile from qctl-core (only qctl-cli builds)
-
-### Phase 3: CI/CD & Distribution
-- [x] Create GitHub Actions workflow for multi-platform builds
-- [x] Add Linux ARM64 build target
-- [x] Fix macOS runner (macos-13 deprecated, use macos-15)
-- [x] Add Homebrew formula with auto-update
-- [x] Add Scoop manifest for Windows
-- [x] Add AUR PKGBUILD for Arch Linux
-- [x] Add Dockerfile for container distribution
-- [x] Add Docker build/push to GHCR in workflow
-- [x] Create comprehensive README
-- [x] Verify GitHub Actions builds pass
-
-### Phase 4: Version & Interactive UX
-- [x] Implement --version flag with build metadata (VersionProvider)
-- [x] Add git-commit-id-maven-plugin for commit hash in version
-- [x] Add version provider to qqq subcommand
-- [x] Refactor init command to be interactive by default
-- [x] Create ConsoleUI class for centralized console I/O
-- [x] Update PromptRunner to use ConsoleUI
-- [x] Template name defaults to new-qqq-application
-- [x] Target directory prompts if not provided
-
-## Pending
-
-### Release
-- [ ] Create first release (v0.1.0)
-- [ ] Verify all distribution channels work
-- [ ] Publish AUR package to aur.archlinux.org
-
-### Template System Enhancements
-- [ ] Add template versioning (semver tags)
-- [ ] Add template signature verification
-- [ ] Add template caching for offline use
-- [ ] Add `qctl qqq update` to check for template updates
-
-### qbit Commands
-- [ ] Implement `qctl qbit add <package>`
-- [ ] Implement `qctl qbit remove <package>`
-- [ ] Implement `qctl qbit update`
-- [ ] Implement lockfile integrity verification
-
-### qrun Commands
-- [ ] Implement `qctl qrun deploy`
-- [ ] Implement `qctl qrun logs`
-- [ ] Implement `qctl qrun rollback`
-- [ ] OCI image building
-
-### qstudio Commands
-- [ ] Implement AI-assisted planning
-- [ ] Integration with Claude API
-
-### Auth System
-- [ ] OAuth2 device flow implementation
-- [ ] Token refresh mechanism
-- [ ] Secure credential storage (keychain integration)
-
-### Testing
-- [ ] Add unit tests for TemplateEngine
-- [ ] Add unit tests for TemplatesHub
-- [ ] Add integration tests for init command
-- [ ] Add golden tests for scaffolded projects
-
-### Documentation
-- [ ] Add man pages
-- [ ] Add shell completion scripts (bash, zsh, fish)
-- [ ] Add examples directory with sample templates
-
-## Distribution Channels
-
-| Channel | Install Command | Manifest |
-|---------|-----------------|----------|
-| Homebrew | `brew tap QRun-IO/qctl && brew install qctl` | `HomebrewFormula/qctl.rb` |
-| Scoop | `scoop bucket add qrun https://github.com/QRun-IO/qctl && scoop install qctl` | `scoop/qctl.json` |
-| AUR | `yay -S qctl-bin` | `aur/PKGBUILD` |
-| Docker | `docker run ghcr.io/qrun-io/qctl` | `Dockerfile` |
-| GitHub | Download from Releases | `.github/workflows/build.yml` |
-
-## Supported Platforms
-
-| Platform | Architecture | Artifact |
-|----------|--------------|----------|
-| Linux | x64 | `qctl-linux-amd64` |
-| Linux | ARM64 | `qctl-linux-arm64` |
-| macOS | Intel | `qctl-macos-amd64` |
-| macOS | Apple Silicon | `qctl-macos-arm64` |
-| Windows | x64 | `qctl-windows-amd64.exe` |
-
-## Notes
-
-### Native Image Requirements
-- GraalVM 21+ required
-- Only `qctl-cli` module has native profile
-- Handlebars requires `--initialize-at-run-time=com.github.jknack.handlebars.helper.DefaultHelperRegistry`
-- Jackson requires reflection config for record types
-
-### Templates Hub
-- Central registry: https://github.com/QRun-IO/templates-hub
-- Templates defined in `templates.yaml`
-- Each template references a git repo with Handlebars templates
-
-### Release Process
-```bash
-git tag v1.0.0
-git push origin v1.0.0
-```
-This triggers GitHub Actions to build, release, and update all package manifests.