working command structure and advanced llm Integration

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Project Architecture: AI-Enhanced CTF Toolchain
 
-This document describes the current architecture, directory layout, core modules, and testing setup of the CTF Toolchain project.
+This document describes the architecture, directory layout, core modules, testing setup, and planned components of the CTF Toolchain project.
 
 ---
 
@@ -18,7 +18,7 @@ The project follows a standard modern Python layout (utilizing `src/` directory
 │       ├── main.py       # CLI Entry Point
 │       ├── commands.py   # CLI Commands and action functions
 │       ├── utils.py      # Core utility functions (file parsing, config, paths)
-│       └── forensics.py  # Placeholder for future forensics analysis tools
+│       └── forensics.py  # Forensics analysis tools
 └── tests/
     ├── env/              # Sandboxed, persistent test environment directories
     └── test_utils.py     # Unit/Integration tests for utility functions
@@ -41,20 +41,54 @@ Provides helper functions for filesystem management and configuration parsing:
 *   `active_competitions(dir)`: Scans the base directory for active competitions, skipping designated helper directories (like `tools`).
 
 ### C. Commands ([commands.py](file:///home/venus/code/ctf/src/ctf/commands.py))
-Houses the logic for each CLI command action:
-*   `test()`: A simple hello-world tester.
+Houses the logic for generic CLI context and active competition commands:
 *   `Set_Challenge(comp, chal, setDirectory)`: Sets the current active challenge/competition context. *(Note: Currently has a `NameError` due to reference to an undefined `state` object.)*
 
+### D. Forensics ([forensics.py](file:///home/venus/code/ctf/src/ctf/forensics.py))
+Implements specialized forensic inspection utilities registered as a nested subgroup under the CLI:
+*   `info`: Inspects target file sizes, reads magic bytes, and warns if extensions do not match detected signatures.
+*   `flag-search`: Extracts printable string sequences (equivalent to GNU `strings`) and matches them against regular expression patterns to find potential flags.
+
 ---
 
 ## 3. CLI Entry Point ([main.py](file:///home/venus/code/ctf/src/ctf/main.py))
 
-*   Currently acts as a simple entry point calling `commands.test()`.
-*   Uses `click` as the planned framework to build a sub-command CLI system (`ctf test`, `ctf set-challenge`, etc.).
+*   Serves as the central CLI entry point via the `main()` function.
+*   Initializes the root Click `cli` group and registers nested sub-groups, such as `forensics_group`.
 
 ---
 
 ## 4. Test Infrastructure
 
 *   **Framework**: `pytest` (run via `uv run pytest`).
-*   **Sandbox**: [tests/env](file:///home/venus/code/ctf/tests/env) acts as a persistent mock directory tree containing temporary competition directories (like `comp1`, `comp2`) to safely test category scanning and config loading/saving without touching actual user data.
+*   **Sandbox**: [tests/env](file:///home/venus/code/ctf/tests/env) acts as a persistent mock directory tree containing temporary competition directories (like `comp1`, `comp2`) and mock files (e.g. valid PNGs, mismatching PDFs, text files with flag payloads) to safely test scanning, parsing, and CLI command execution without touching actual user data.
+
+---
+
+## 5. Planned Architectural Components
+
+### A. File Scraper & Extended Configuration
+*   A scraping module to fetch details/files for challenges or competitions.
+*   Integration with an expanded configuration schema in [config.toml](file:///home/venus/code/ctf/config.toml) to store credentials, URLs, and directory preferences.
+
+### B. Download Organizer & Challenge Progress Documenter
+*   Monitoring or organizing downloaded challenge assets (e.g., from the browser's downloads folder) and sorting them into the correct competition/challenge subdirectories.
+*   An automated mechanism to log commands, notes, and milestones, providing clean progress documentation.
+
+### C. Forensics Metadata Expansion
+*   Extend forensics capabilities inside [forensics.py](file:///home/venus/code/ctf/src/ctf/forensics.py) to extract file-specific metadata (e.g., EXIF header extraction for JPG/PNG files, archive contents listing, and PE section analysis).
+
+---
+
+## 6. CLI Data Flow & Presentation Guidelines
+
+### A. Model-View Separation
+All CLI command modules (such as [forensics.py](file:///home/venus/code/ctf/src/ctf/forensics.py)) must separate data extraction logic from command-line rendering.
+*   **Data Models**: Standard Python `@dataclass` objects should be defined to house parsed metadata (e.g., file size, magic bytes, detected types, warnings, and format-specific attributes).
+*   **Decoupled Parsers**: Extraction helper functions must return these dataclass instances instead of printing directly to standard output. This keeps the core parser functions purely functional and fully testable in unit tests.
+
+### B. Console Rendering with `rich`
+To provide a clean, modern, and easily readable console output without building a full terminal user interface (TUI):
+*   **Tables**: Use `rich.table.Table` to align and structure multi-column metadata outputs.
+*   **Formatting & Alerts**: Utilize `rich.console` or `rich.panel.Panel` to highlight warnings (such as signature/extension mismatches) with distinct styling and colors.
+*   **JSON Serialization**: Dataclasses should be easily convertible to dictionaries to support raw JSON output options for scripting pipelines.