mkpfs 0.0.1__tar.gz

mkpfs-0.0.1/.claude/MEMORY.md

@@ -0,0 +1,199 @@
+# Project Memory
+
+This file is a curated, durable knowledge base for active development and testing in this repository.
+Keep entries concise, source-backed, and oriented toward repeatable workflows.
+
+## How To Use This Memory
+
+- Read this file first for high-signal project context before deep investigation.
+- Treat this as a navigation layer; use linked source files as the ground truth.
+- Prefer adding compact bullets over long prose.
+- When behavior changes, update the related section and keep references current.
+
+## Core References
+
+- [PyPI project guidelines](rules/pypi-project-guidelines.md) — packaging checklist, README guidance, and release-validation references.
+- [Root agent rules](../AGENTS.md) — canonical coding, testing, and style expectations used by local agent workflows.
+- [Claude agent mirror](../CLAUDE.md) — synchronized agent guidance used by local `.claude` workflows.
+- Architecture map: keep CLI wiring in [`mkpfs/cli.py`](../mkpfs/cli.py), and keep PFS format/build/inspection logic in [`mkpfs/pfs.py`](../mkpfs/pfs.py).
+- Shared modules: constants in [`mkpfs/consts.py`](../mkpfs/consts.py), progress/tree scan in [`mkpfs/pbar.py`](../mkpfs/pbar.py), helpers in [`mkpfs/utils.py`](../mkpfs/utils.py).
+- Current CLI surface: `create`, `check` (`verify` alias), `ls`, `info`, `analyze` (`analyse` alias), and `extract`; keep docs and smoke tests aligned.
+- CLI smoke test anchor: [`tests/test_main.py`](../tests/test_main.py) validates help output text and should be updated when CLI description text changes.
+- Convenience validation script: [`run-tests.sh`](../run-tests.sh) runs `uv sync`, installs pre-commit hooks, runs Ruff format/check with `--fix`, then runs pytest.
+
+## Related Projects Knowledge Base
+
+### ShadowMountPlus
+
+- Repository: https://github.com/drakmor/ShadowMountPlus
+- Submodule folder: [related-projects/shadowmountplus](../related-projects/shadowmountplus)
+- Maintained research report: [related-projects/ShadowMountPlus.md](../related-projects/ShadowMountPlus.md)
+
+Short summary:
+
+- ShadowMountPlus auto-detects game folders and image files, mounts them, stages metadata, and registers titles for launch.
+- Supported image extensions: .ffpkg (ufs), .exfat (exfatfs), .ffpfs (pfs, experimental).
+- For .ffpfs, mounting uses LVD attach + pfs nmount options and then validates mounted block size vs chosen sector size.
+- Practical compatibility requirements for generated images include image-root layout, valid sce_sys/param.json, and eboot.bin present at image root.
+
+How to inspect this knowledge quickly:
+
+- Start with the report: [related-projects/ShadowMountPlus.md](../related-projects/ShadowMountPlus.md).
+- Then inspect original source code under: [related-projects/shadowmountplus](../related-projects/shadowmountplus).
+- Priority files for mount and filesystem behavior:
+	- [related-projects/shadowmountplus/src/sm_image.c](../related-projects/shadowmountplus/src/sm_image.c)
+	- [related-projects/shadowmountplus/include/sm_mount_defs.h](../related-projects/shadowmountplus/include/sm_mount_defs.h)
+	- [related-projects/shadowmountplus/src/sm_mount_device.c](../related-projects/shadowmountplus/src/sm_mount_device.c)
+	- [related-projects/shadowmountplus/src/sm_scan_tree.c](../related-projects/shadowmountplus/src/sm_scan_tree.c)
+	- [related-projects/shadowmountplus/src/sm_scan.c](../related-projects/shadowmountplus/src/sm_scan.c)
+	- [related-projects/shadowmountplus/src/sm_gameinfo.c](../related-projects/shadowmountplus/src/sm_gameinfo.c)
+	- [related-projects/shadowmountplus/src/sm_install.c](../related-projects/shadowmountplus/src/sm_install.c)
+	- [related-projects/shadowmountplus/src/sm_filesystem.c](../related-projects/shadowmountplus/src/sm_filesystem.c)
+	- [related-projects/shadowmountplus/src/sm_config_mount.c](../related-projects/shadowmountplus/src/sm_config_mount.c)
+	- [related-projects/shadowmountplus/config.ini.example](../related-projects/shadowmountplus/config.ini.example)
+
+### PKGTool
+
+- Repository/source: https://github.com/thesupersonic16/PKGTool
+- Artifact folder: [related-projects/pkgtool](../related-projects/pkgtool)
+- Deep summary: [related-projects/pkgtool.md](../related-projects/pkgtool.md)
+
+Short summary:
+
+- PKGTool provides a practical parser/extractor for `.pkg` archives through `PKGArchive` and a partial repack writer.
+- On-disk table entries are fixed `0x54` bytes and use little-endian integer fields in this implementation.
+- Decompression is custom marker/back-reference based (`ReadAndDecompress`) and loops to decompressed size.
+- Writer currently leaves CRC unimplemented and writes entries as uncompressed with zeroed compression/attribute block.
+- Repack behavior is non-recursive and effectively basename-oriented by default, which matters for faithful recreation tooling.
+
+How to inspect this knowledge quickly:
+
+- Start with summary: [related-projects/pkgtool.md](../related-projects/pkgtool.md)
+- Validate against source folder: [related-projects/pkgtool](../related-projects/pkgtool)
+- Priority files/pages:
+	- [related-projects/pkgtool/PKGTool/PKGArchive.cs](../related-projects/pkgtool/PKGTool/PKGArchive.cs)
+	- [related-projects/pkgtool/PKGTool/Program.cs](../related-projects/pkgtool/PKGTool/Program.cs)
+	- [related-projects/pkgtool/PKGTool/PKGTool.csproj](../related-projects/pkgtool/PKGTool/PKGTool.csproj)
+	- [related-projects/pkgtool/PKGTool.sln](../related-projects/pkgtool/PKGTool.sln)
+	- [related-projects/pkgtool/.gitmodules](../related-projects/pkgtool/.gitmodules)
+	- [related-projects/pkgtool/HedgeLib/HedgeLib/IO/ExtendedBinary.cs](../related-projects/pkgtool/HedgeLib/HedgeLib/IO/ExtendedBinary.cs)
+	- [related-projects/pkgtool/HedgeLib/HedgeLib/Archives/Archive.cs](../related-projects/pkgtool/HedgeLib/HedgeLib/Archives/Archive.cs)
+	- [related-projects/pkgtool/HedgeLib/HedgeLib/Archives/ArchiveFile.cs](../related-projects/pkgtool/HedgeLib/HedgeLib/Archives/ArchiveFile.cs)
+
+### LibOrbisPkg
+
+- Repository/source: https://github.com/maxton/LibOrbisPkg
+- Artifact folder: [related-projects/liborbispkg](../related-projects/liborbispkg)
+- Deep summary: [related-projects/liborbispkg.md](../related-projects/liborbispkg.md)
+
+Short summary:
+
+- LibOrbisPkg is a full PKG and PFS toolkit with reusable library code, GUI and CLI tools, tests, and Binary Template references.
+- The PFS implementation includes tree modeling, inode and dirent serialization, flat path table generation, signed outer-image layout, and optional AES-XTS encryption.
+- The PKG layer derives developer-controlled keys from Content ID and passcode, exposes fake-PKG EKPFS recovery, and carries the PFS offsets, flags, and digests needed to open nested images.
+- PFSC support is asymmetric: the reader handles compressed and direct sectors, while the bundled writer emits header plus full-block mapping for nested `pfs_image.dat` content.
+- A notable compatibility detail is the `newCrypt` branch in `PfsGenEncKey`, which is triggered from PKG `pfs_flags` during PFS reads.
+
+How to inspect this knowledge quickly:
+
+- Start with summary: [related-projects/liborbispkg.md](../related-projects/liborbispkg.md)
+- Validate against source folder: [related-projects/liborbispkg](../related-projects/liborbispkg)
+- Priority files/pages:
+	- [related-projects/liborbispkg/LibOrbisPkg/PFS/PFSBuilder.cs](../related-projects/liborbispkg/LibOrbisPkg/PFS/PFSBuilder.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PFS/PfsReader.cs](../related-projects/liborbispkg/LibOrbisPkg/PFS/PfsReader.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PFS/PfsStructs.cs](../related-projects/liborbispkg/LibOrbisPkg/PFS/PfsStructs.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/Util/Crypto.cs](../related-projects/liborbispkg/LibOrbisPkg/Util/Crypto.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PFS/FlatPathTable.cs](../related-projects/liborbispkg/LibOrbisPkg/PFS/FlatPathTable.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PFS/FSTree.cs](../related-projects/liborbispkg/LibOrbisPkg/PFS/FSTree.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PFS/PFSCReader.cs](../related-projects/liborbispkg/LibOrbisPkg/PFS/PFSCReader.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PFS/PFSCWriter.cs](../related-projects/liborbispkg/LibOrbisPkg/PFS/PFSCWriter.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PKG/Pkg.cs](../related-projects/liborbispkg/LibOrbisPkg/PKG/Pkg.cs)
+	- [related-projects/liborbispkg/LibOrbisPkg/PKG/Entry.cs](../related-projects/liborbispkg/LibOrbisPkg/PKG/Entry.cs)
+	- [related-projects/liborbispkg/PkgTool/Program.cs](../related-projects/liborbispkg/PkgTool/Program.cs)
+	- [related-projects/liborbispkg/LibOrbisPkgTests/PfsReaderTests.cs](../related-projects/liborbispkg/LibOrbisPkgTests/PfsReaderTests.cs)
+	- [related-projects/liborbispkg/LibOrbisPkgTests/PkgBuildTest.cs](../related-projects/liborbispkg/LibOrbisPkgTests/PkgBuildTest.cs)
+
+### LibOrbisPkg Wiki
+
+- Repository/source: https://github.com/maxton/LibOrbisPkg.wiki.git
+- Artifact folder: [related-projects/liborbispkg-wiki](../related-projects/liborbispkg-wiki)
+- Deep summary: [related-projects/liborbispkg-wiki.md](../related-projects/liborbispkg-wiki.md)
+
+Short summary:
+
+- The wiki is a compact orientation layer for the LibOrbisPkg library plus the PkgEditor and PkgTool frontends.
+- Its highest-value page is the PKG crypto note covering passcode-derived keys, EKPFS, PFS key derivation, and `ENTRY_KEYS` / `IMAGE_KEY` roles.
+- The PkgEditor page captures user-facing PKG build requirements such as the 36-character content ID format and the required `Image0/sce_sys/param.sfo`.
+- The library page is best used as a namespace and capability map, not a stable API contract.
+- The PkgTool wiki page is currently only a placeholder and should not be treated as authoritative CLI documentation.
+
+How to inspect this knowledge quickly:
+
+- Start with summary: [related-projects/liborbispkg-wiki.md](../related-projects/liborbispkg-wiki.md)
+- Validate against snapshot folder: [related-projects/liborbispkg-wiki](../related-projects/liborbispkg-wiki)
+- Priority files/pages:
+	- [related-projects/liborbispkg-wiki/PKG-Information.md](../related-projects/liborbispkg-wiki/PKG-Information.md)
+	- [related-projects/liborbispkg-wiki/PkgEditor.md](../related-projects/liborbispkg-wiki/PkgEditor.md)
+	- [related-projects/liborbispkg-wiki/Library.md](../related-projects/liborbispkg-wiki/Library.md)
+	- [related-projects/liborbispkg-wiki/Home.md](../related-projects/liborbispkg-wiki/Home.md)
+  - [related-projects/liborbispkg-wiki/PkgTool.md](../related-projects/liborbispkg-wiki/PkgTool.md)
+  - [related-projects/liborbispkg-wiki/manifest.md](../related-projects/liborbispkg-wiki/manifest.md)
+
+### kstuff-lite
+
+- Repository/source: https://github.com/EchoStretch/kstuff-lite
+- Artifact folder: [related-projects/kstuff-lite](../related-projects/kstuff-lite)
+- Deep summary: [related-projects/kstuff-lite.md](../related-projects/kstuff-lite.md)
+
+Short summary:
+
+- kstuff-lite is a PS5 payload bundle with a loader, kernel syscall hooks, mount automation, and crypto helpers.
+- The loader can mount UFS, PFS, or exFAT images from a source directory and falls back to the raw folder path if mounting fails.
+- `KSTUFF_OBS=1` enables observability artifacts and shared-area snapshot support.
+- The crypto stack focuses on `fpkg`, `FSELF`, and debug NPDRM handling, with small caches for repeated HMAC and XTS work.
+
+How to inspect this knowledge quickly:
+
+- Start with summary: [related-projects/kstuff-lite.md](../related-projects/kstuff-lite.md)
+- Validate against source folder: [related-projects/kstuff-lite](../related-projects/kstuff-lite)
+- Priority files:
+  - [related-projects/kstuff-lite/README.md](../related-projects/kstuff-lite/README.md)
+  - [related-projects/kstuff-lite/ci-ps5-kstuff-ldr.sh](../related-projects/kstuff-lite/ci-ps5-kstuff-ldr.sh)
+  - [related-projects/kstuff-lite/.gitmodules](../related-projects/kstuff-lite/.gitmodules)
+  - [related-projects/kstuff-lite/ps5-kstuff/Makefile](../related-projects/kstuff-lite/ps5-kstuff/Makefile)
+  - [related-projects/kstuff-lite/ps5-kstuff-ldr/main.c](../related-projects/kstuff-lite/ps5-kstuff-ldr/main.c)
+  - [related-projects/kstuff-lite/ps5-kstuff/uelf/main.c](../related-projects/kstuff-lite/ps5-kstuff/uelf/main.c)
+  - [related-projects/kstuff-lite/ps5-kstuff/uelf/pfs_crypto.c](../related-projects/kstuff-lite/ps5-kstuff/uelf/pfs_crypto.c)
+  - [related-projects/kstuff-lite/ps5-kstuff/uelf/fpkg.c](../related-projects/kstuff-lite/ps5-kstuff/uelf/fpkg.c)
+  - [related-projects/kstuff-lite/ps5-kstuff/uelf/fself.c](../related-projects/kstuff-lite/ps5-kstuff/uelf/fself.c)
+  - [related-projects/kstuff-lite/ps5-kstuff/uelf/npdrm.c](../related-projects/kstuff-lite/ps5-kstuff/uelf/npdrm.c)
+
+### Other Knowledge Sources
+
+- Repository/source: mixed local archive from PSDevWiki, ShadPKG docs, and Wololo
+- Artifact folder: [related-projects/other-knowledge-sources](../related-projects/other-knowledge-sources)
+- Deep summary: [related-projects/other-knowledge-sources.md](../related-projects/other-knowledge-sources.md)
+
+Short summary:
+
+- This archive combines permanent PSDevWiki snapshots, a detailed ShadPKG HOWWORKS markdown, and a Wololo article preserving Flatz's FPKG writeup.
+- The ShadPKG markdown is the strongest implementation-level source here for PKG decryption, PFS key derivation, AES-XTS, PFSC block handling, and extraction flow.
+- The PSDevWiki PFS snapshot and its local derivative index are the clearest structure-oriented references for headers, inode and dirent layout, `uroot`, and `flat_path_table` behavior.
+- Provenance and re-export details are tracked inside the folder README and `source-manifest.md`, including archive date, publication or revision identity, and upstream URLs.
+
+How to inspect this knowledge quickly:
+
+- Start with summary: [related-projects/other-knowledge-sources.md](../related-projects/other-knowledge-sources.md)
+- Validate against archive folder: [related-projects/other-knowledge-sources](../related-projects/other-knowledge-sources)
+- Priority files/pages:
+	- [related-projects/other-knowledge-sources/shadpkg-howworks-raw.md](../related-projects/other-knowledge-sources/shadpkg-howworks-raw.md)
+	- [related-projects/other-knowledge-sources/psdevwiki-pfs-index.md](../related-projects/other-knowledge-sources/psdevwiki-pfs-index.md)
+	- [related-projects/other-knowledge-sources/psdevwiki-pfs.html](../related-projects/other-knowledge-sources/psdevwiki-pfs.html)
+	- [related-projects/other-knowledge-sources/psdevwiki-pkg-files.html](../related-projects/other-knowledge-sources/psdevwiki-pkg-files.html)
+	- [related-projects/other-knowledge-sources/source-manifest.md](../related-projects/other-knowledge-sources/source-manifest.md)
+
+## Update Standard
+
+- Keep each entry factual, short, and tied to concrete source links.
+- Prefer stable paths over temporary artifacts.
+- Do not store scratch notes here; use tmp for transient work.

mkpfs-0.0.1/.claude/rules/html-reporting.md

@@ -0,0 +1,23 @@
+---
+name: HTML reporting
+description: How to create polished HTML reports for detailed answers and research
+type: reference
+---
+
+When the user asks for a detailed answer or research, produce the normal text response and 
+also generate a companion modern and detailed HTML report.
+
+Save the HTML file under `./tmp/` and include a clickable markdown link to it in the response.
+
+Make the report clean and readable:
+
+- Use a proper HTML5 document with a descriptive title.
+- Include a short executive summary near the top.
+- Organize the body with clear section headings.
+- Use readable spacing, a constrained content width, and simple typography.
+- Style code blocks, tables, and links clearly.
+- Include a references section when sources are involved.
+
+Keep the HTML self-contained unless external assets are unavoidable. Prefer inline CSS for simple, portable reports.
+
+Do not replace the chat response with HTML; the HTML is a companion artifact.

mkpfs-0.0.1/.claude/rules/markdown-style.md

@@ -0,0 +1,118 @@
+---
+name: markdown-style
+description: Project conventions for README, wiki, and Markdown formatting (icons, badges, colors, tone, and file layout)
+type: project
+---
+
+# Markdown Style Guide
+
+Purpose: capture the visual and prose style we use across README.md and short wiki-style markdown files so contributors produce consistent, high-quality docs.
+
+Keep this file short and actionable. If you change visual assets or global colors, update this rule.
+
+## High-level tone and voice
+- Practical, concise, and slightly technical: assume the reader knows basic tooling but keep onboarding friendly.
+- Write in active voice, present tense. Prefer short paragraphs and bullet lists.
+- Avoid marketing hyperbole, be factual about capabilities and workflows.
+- Do not foreground lifecycle labels such as alpha or beta in user-facing docs unless explicitly requested.
+
+## Visual identity
+- Primary brand color: blue. Example palette (use these hex colors in images and banners):
+  - Primary: #2563EB (blue)
+  - Accent: #3B82F6 (light blue)
+  - Surface / panels: #EFF6FF / #DBEAFE (very pale blues)
+  - Neutral dark: #0F172A / #0B1733 (text, dark backgrounds)
+- Iconography: use UTF-8 emoji for section headings and quick-links. Keep icons consistent and semantically appropriate. Examples:
+  - 📚 Documentation
+  - 📦 Install
+  - ⌨️ Command Overview
+  - 🖥️ GUI
+  - 💙 Thanks (contributors)
+  - 🔗 Related projects
+  - 💖 Sponsor
+- Badges: prefer shields.io for badges. Style: `style=for-the-badge` for the top cluster. Include: status, PyPI (version), license, Python version. Use flat-square for a second-row group when needed.
+
+## Hero / title block
+- Center the hero block. Include in order:
+  1. Project icon image (assets/images/icon.png) — rounded with subtle shadow and light border. Example inline style: `style="border-radius:30px; box-shadow:0 10px 30px rgba(37,99,235,0.18); border:4px solid rgba(14,165,233,0.08);"`.
+  2. H1: `ProjectName: ShortTagline` (e.g., `MkPFS: Make PSF`). Keep the H1 short.
+  3. One-line product sentence (H3 or short paragraph) that expands the acronym and lists the three delivery surfaces when relevant (CLI, library, GUI).
+   4. Top badge cluster (status, PyPI, license, python).
+  5. Quick-links row (emoji-prefixed links separated by middot ·). Order:
+      - 📦 Install · ⌨️ Commands · 💙 Thanks · 🔗 Related projects
+     - then a blank line
+     - then the sponsor entry on its own line: `💖 Sponsor` (linked badge)
+
+## Images and screenshots
+- Store project visuals under `assets/images/` (not `tmp/` and not scattered). Use descriptive names: `hero-banner.svg`, `screenshot-create.svg`, `screenshot-check.svg`, `screenshot-gui.svg`.
+- PNG icons ok for favicon/logo; larger illustrations should be SVG when possible.
+- Image styling in README: reference images by path only (no base64). Use alt text. Avoid calling them "placeholders" in public docs; instead caption them (e.g., "Screenshot: Create workflow").
+
+## Section structure and headings
+- Use emoji-prefixed headings for main sections. Keep consistent H2/H3 hierarchy.
+- Typical README section order:
+  1. Why / Overview
+  2. Main Features (short bullets)
+  3. Installation
+  4. Command Overview (subcommands listed with short purpose; do not enumerate all flags)
+  5. GUI (if present)
+  6. Sponsorship (prominent, near top/hero or before contributors)
+  7. Special thanks and Contributors (short list)
+  8. Related projects (single curated list of external links)
+   9. Contributing (short callout linking to CONTRIBUTING.md)
+
+## Command blocks and examples
+- Show subcommand usage at the top-level only. For each subcommand, include a one-line summary and a single example invocation (no exhaustive param list in README). Example style:
+
+```bash
+mkpfs create --path ./input --output ./game.ffpfs
+```
+
+- Use the terminal icon (⌨️) for the Command Overview heading.
+
+## Links and documentation references
+- Prefer linking to in-repo guidance in `README.md` or `related-projects/`.
+- Keep public links focused on the repository, release artifacts, and source material.
+
+## Style of writing and micro-rules
+- Keep sentences short (<= 24 words where practical).
+- Use code font (`code`) for file names and command tokens.
+- Use backtick code blocks for CLI examples; use fenced triple-backtick with language when showing code.
+- Use bullets for feature lists and checklists.
+- Keep sponsorship ask polite and specific (what support buys: tests, packaging, docs).
+- When writing English prose for README, docs, comments, or wiki pages, avoid using the em dash (—). Prefer commas, hyphens, 'title: subtitle' structure, or a semicolon to separate related ideas in the same paragraph.
+- Do NOT use placeholder language that signals unfinished work (remove lines like: "The screenshots below are polished placeholders…").
+
+## Metadata alignment
+- Ensure README top claims align with `pyproject.toml` (name, version, supported Python, license, project URLs).
+- If README content changes project positioning significantly, update `pyproject.toml` accordingly.
+
+## Contribution & CI notes
+- Include a short contributing pointer linking to `CONTRIBUTING.md`.
+- Example common-checks snippet should reference our tooling:
+
+```bash
+uv sync --group dev
+uv run --frozen pytest
+uv run --frozen ruff check .
+uv run --frozen ruff format .
+```
+
+- Do not commit files from `./tmp/`.
+
+## File-level formatting rules
+- Keep line-length reasonable (wrap at ~100 columns for prose in README).
+- Use Markdown (CommonMark) only — avoid HTML unless necessary for image styling (small inline style for hero icon allowed as above).
+
+## Enforcement and verification
+- Before merging README or major docs changes run:
+  - `uv run --frozen ruff check .`
+  - `uv run --frozen pytest`
+
+## Examples and snippets
+- Hero icon HTML: use a rounded image with subtle shadow and small border (see top of README for exact style example).
+- Quick links format: Emoji + text links separated by middot `·`. Put Sponsor on its own line after a blank line.
+
+---
+
+Keep this guideline lightweight — update it when the visual direction changes or when new global assets (icons, banners) are added.

mkpfs-0.0.1/.claude/rules/pypi-project-guidelines.md

@@ -0,0 +1,38 @@
+---
+name: PyPI packaging guidelines
+description: Practical checklist for publishing a good Python library to PyPI
+type: reference
+---
+
+Use `pyproject.toml` as the primary source of packaging metadata.
+
+Keep core metadata explicit: name, version, supported Python versions, runtime dependencies, license, README, keywords, classifiers, and project URLs.
+
+Build and publish both source distributions and wheels.
+
+Prefer a package directory layout for multi-file libraries.
+
+Keep dependency groups separate from runtime dependencies when possible.
+
+For a small pure-Python library, keep metadata centralized, document the project clearly in the README, and ensure the README renders safely on PyPI.
+
+## README guidance
+
+Use a supported format: Markdown, reStructuredText, or plain text.
+
+Keep the README at the repository root and use it as the long description.
+
+Make the content renderer-safe for PyPI and validate builds before publishing.
+
+## Repo-specific notes
+
+- This repository is an active package (`mkpfs`) with CLI entrypoint `mkpfs = "mkpfs.cli:main"`.
+- Keep the public README accurate for current command surface: `create`, `check` (`verify` alias), `ls`, `info`, `analyze` (`analyse` alias), and `extract`.
+- Validate release artifacts with `uv build` and `uv run --frozen twine check dist/*` before publishing.
+- Use `./tmp/` only for ephemeral planning, scratch files, and generated HTML reports.
+
+## References
+
+- https://packaging.python.org/en/latest/overview/
+- https://packaging.python.org/en/latest/specifications/
+- https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/

mkpfs-0.0.1/.claude/rules/readme-style.md

@@ -0,0 +1,117 @@
+---
+name: readme-style-guidelines
+description: Project conventions for README, wiki, and Markdown formatting (icons, badges, colors, tone, and file layout)
+type: project
+---
+
+# README & Markdown Style Guide
+
+Purpose: capture the visual and prose style we use across README.md and short wiki-style markdown files so contributors produce consistent, high-quality docs.
+
+Keep this file short and actionable. If you change visual assets or global colors, update this rule.
+
+## High-level tone and voice
+- Practical, concise, and slightly technical: assume the reader knows basic tooling but keep onboarding friendly. 
+- Write in active voice, present tense. Prefer short paragraphs and bullet lists.
+- Avoid marketing hyperbole, be factual about capabilities and workflows.
+- Do not foreground lifecycle labels such as alpha or beta in user-facing docs unless explicitly requested.
+
+## Visual identity
+- Primary brand color: blue. Example palette (use these hex colors in images and banners):
+  - Primary: #2563EB (blue)
+  - Accent: #3B82F6 (light blue)
+  - Surface / panels: #EFF6FF / #DBEAFE (very pale blues)
+  - Neutral dark: #0F172A / #0B1733 (text, dark backgrounds)
+- Iconography: use UTF-8 emoji for section headings and quick-links. Keep icons consistent and semantically appropriate. Examples:
+  - 📚 Documentation
+  - 📦 Install
+  - ⌨️ Command Overview
+  - 🖥️ GUI
+  - 💙 Thanks (contributors)
+  - 🔗 Related projects
+  - 💖 Sponsor
+- Badges: prefer shields.io for badges. Style: `style=for-the-badge` for the top cluster. Include: status, PyPI (version), license, Python version. Use flat-square for a second-row group when needed.
+
+## Hero / title block
+- Center the hero block. Include in order:
+  1. Project icon image (assets/images/icon.png) — rounded with subtle shadow and light border. Example inline style: `style="border-radius:30px; box-shadow:0 10px 30px rgba(37,99,235,0.18); border:4px solid rgba(14,165,233,0.08);"`.
+  2. H1: `ProjectName: ShortTagline` (e.g., `MkPFS: Make PSF`). Keep the H1 short.
+  3. One-line product sentence (H3 or short paragraph) that expands the acronym and lists the three delivery surfaces when relevant (CLI, library, GUI).
+   4. Top badge cluster (status, PyPI, license, python).
+  5. Quick-links row (emoji-prefixed links separated by middot ·). Order:
+      - 📦 Install · ⌨️ Commands · 🖥️ GUI · 💙 Thanks · 🔗 Related projects
+     - then a blank line
+     - then the sponsor entry on its own line: `💖 Sponsor` (linked badge)
+
+## Images and screenshots
+- Store project visuals under `assets/images/` (not `tmp/` and not scattered). Use descriptive names: `hero-banner.svg`, `screenshot-create.svg`, `screenshot-check.svg`, `screenshot-gui.svg`.
+- PNG icons ok for favicon/logo; larger illustrations should be SVG when possible.
+- Image styling in README: reference images by path only (no base64). Use alt text. Avoid calling them “placeholders” in public docs; instead caption them (e.g., “Screenshot: Create workflow”).
+
+## Section structure and headings
+- Use emoji-prefixed headings for main sections. Keep consistent H2/H3 hierarchy.
+- Typical README section order:
+  1. Why / Overview
+  2. Main Features (short bullets)
+  3. Installation
+  4. Command Overview (subcommands listed with short purpose; do not enumerate all flags)
+  5. GUI (if present)
+  6. Sponsorship (prominent, near top/hero or before contributors)
+  7. Contributors & Thanks (short list)
+  8. Related projects (single curated list)
+   9. Contributing (short callout linking to CONTRIBUTING.md)
+
+## Command blocks and examples
+- Show subcommand usage at the top-level only. For each subcommand, include a one-line summary and a single example invocation (no exhaustive param list in README). Example style:
+
+```bash
+mkpfs create --path ./input --output ./game.ffpfs
+```
+
+- Use the terminal icon (⌨️) for the Command Overview heading.
+
+## Links and documentation references
+- Prefer linking to in-repo guidance in `README.md` or `related-projects/`.
+- Keep public links focused on the repository, release artifacts, and source material.
+
+## Style of writing and micro-rules
+- Keep sentences short (<= 24 words where practical).
+- Use code font (`code`) for file names and command tokens.
+- Use backtick code blocks for CLI examples; use fenced triple-backtick with language when showing code.
+- Use bullets for feature lists and checklists.
+- Keep sponsorship ask polite and specific (what support buys: tests, packaging, docs).
+- Do NOT use placeholder language that signals unfinished work (e.g., remove lines like: “The screenshots below are polished placeholders…”).
+
+## Metadata alignment
+- Ensure README top claims align with `pyproject.toml` (name, version, supported Python, license, project URLs).
+- If README content changes project positioning significantly, update `pyproject.toml` accordingly.
+
+## Contribution & CI notes
+- Include a short contributing pointer linking to `CONTRIBUTING.md`.
+- Example common-checks snippet should reference our tooling:
+
+```bash
+uv sync --group dev
+uv run --frozen pytest
+uv run --frozen ruff check .
+uv run --frozen ruff format .
+```
+
+- Do not commit files from `./tmp/`.
+
+## File-level formatting rules
+- Keep line-length reasonable (wrap at ~100 columns for prose in README).
+- Use Markdown (CommonMark) only — avoid HTML unless necessary for image styling (small inline style for hero icon allowed as above).
+
+## Enforcement and verification
+- Before merging README or major docs changes run:
+  - `uv run --frozen ruff check .`
+  - `uv run --frozen pytest`
+
+## Examples and snippets
+- Hero icon HTML: use a rounded image with subtle shadow and small border (see top of README for exact style example).
+- Quick links format: Emoji + text links separated by middot `·`. Put Sponsor on its own line after a blank line.
+
+---
+
+Keep this guideline lightweight — update it when the visual direction changes or when new global assets (icons, banners) are added.

mkpfs-0.0.1/.claude/rules/tmp-usage.md

@@ -0,0 +1,15 @@
+---
+name: Temporary workspace usage
+description: Guidance for using ./tmp for scratch files, planning, and generated artifacts
+type: reference
+---
+
+Use `./tmp/` for transient work only: planning notes, scratch files, ad hoc exports, generated reports, and other temporary artifacts.
+
+Keep one-off filenames descriptive enough to find later, but never rely on anything in `./tmp/` as permanent project state.
+
+Do not commit files from `./tmp/`.
+
+If a task needs a temporary helper script or intermediate output, put it under `./tmp/` and delete it when the work is done.
+
+Prefer `./tmp/<task-name>/` for grouped work so a single task can be cleaned up quickly.

mkpfs-0.0.1/.claude/rules/venv-activation.md

@@ -0,0 +1,26 @@
+# Local .venv Activation Rule
+
+It is **CRITICAL** that the local `.venv` is activated before executing any command in this project.
+
+Most tools, scripts, and workflows in this repository depend on the correct Python environment, and important code such as `./run-tests.sh` will fail or produce inconsistent results without it.
+
+- You MUST activate the local `.venv` before running any commands, tests, or scripts, including but not limited to `./run-tests.sh`, CLI invocations, and automation tasks.
+- Activating the `.venv` ensures all dependencies, correct Python version (3.11), and environment variables are present and used for the session.
+- Do not run project scripts using the system Python or a globally installed Python interpreter.
+
+**To activate the local environment:**
+
+On macOS/Linux:
+```bash
+source .venv/bin/activate
+```
+On Windows:
+```cmd
+.venv\Scripts\activate
+```
+
+- Running without the `.venv` activated may lead to missing dependencies, wrong Python version, or failures in core CLI and testing commands.
+- If you see errors related to module imports, pip/uv/pytest/ruff not found, or Python version mismatch, double-check your environment.
+
+**Summary:**
+> Always `activate` the `.venv` before you do anything in this project.

mkpfs-0.0.1/.claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run:*)",
+      "Bash(./run-tests.sh)",
+      "WebSearch",
+      "Bash(python -m twine check dist/*)",
+      "Bash(uv build:*)",
+      "Bash(python3.11 --version)",
+      "Bash(git status:*)"
+    ]
+  },
+  "autoFix": {
+    "enabled": true,
+    "format": "uv run --frozen ruff format .",
+    "lint": "uv run --frozen ruff check . --fix",
+    "test": "uv run --frozen pytest",
+    "maxRetries": 3,
+    "timeout": 60000
+  }
+}

mkpfs-0.0.1/.claude/skills/fix-tests/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: fix-tests
+description: Run checks and fix failing tests before push.
+context: fork
+---
+
+# Fix Tests
+
+Use this skill when the goal is to get the branch ready to push by repeatedly running checks and fixing failures.
+
+1. Inspect what changed.
+   - Run `git status --short`.
+   - Review current diffs with `git diff --stat` and `git diff`.
+
+2. Run the full local validation flow.
+   - Run pre-commit checks with `uv run --frozen pre-commit run --all-files`.
+   - Run `./run-tests.sh`.
+
+3. Loop until clean.
+   - Group related failures by root cause.
+   - Apply minimal readable fixes that keep behavior stable unless tests show the behavior is incorrect.
+   - Add or update focused tests for each bug fix.
+   - Re-run pre-commit and the test script after each fix batch.
+
+4. Final readiness check.
+   - Confirm both commands pass with no failures.
+   - Summarize what was fixed and list any remaining risks or follow-ups before push.
+

mkpfs-0.0.1/.claude/skills/html-reporting/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: html-reporting
+description: Generate a polished companion HTML report for detailed answers, checks, and verification outputs.
+context: fork
+---
+
+# HTML Reporting Skill
+
+Use this skill whenever the user requests a detailed answer, research, verification, or any "check" or "report" about code, tests, or project state. The skill produces two artifacts:
+
+1. A normal chat response (always required).
+2. A companion, self-contained HTML5 report saved under ./tmp/ with a clickable path included in the chat response.
+
+Guidelines and steps
+
+1. When to use
+   - The user explicitly asks for a report, detailed answer, verification, or research.
+   - The user asks for anything to be "checked", "reported", "verified", "audited", or needs a long-form explanation that benefits from a browsable artifact.
+
+2. Produce the normal chat response first
+   - Keep the chat response concise and to the point.
+   - Do not replace or delay the chat response in favor of the HTML. The HTML is a companion artifact only.
+
+3. Generate the HTML report
+   - Save it under ./tmp/. Use a descriptive filename: <task>-report-YYYYMMDD-HHMMSS.html (example: tmp/report-verify-tests-20260514-102530.html).
+   - The report must be a complete HTML5 document with a descriptive <title>.
+   - Include a short executive summary near the top (1-3 sentences).
+   - Organize sections with clear headings: Summary, Findings, Commands Run, Evidence (logs, test output), Recommendations, References.
+   - Use simple inline CSS for readable typography, constrained width, and spacing.
+   - Style code blocks with monospace font and preserve whitespace.
+   - When sources are used, include a References section with clickable links.
+   - Keep the file self-contained (inline CSS). Avoid external assets unless unavoidable.
+
+4. What to include in the report
+   - A brief context paragraph describing why the report was generated.
+   - Exact commands that were run and their outputs (truncate very large outputs but note truncation and where full output can be found if applicable).
+   - If tests were run, show failing tests and short excerpts of failure traces.
+   - A clear Recommendations section with next steps.
+
+5. Safety and repo hygiene
+   - Save reports only under ./tmp/.
+   - Do not commit files from ./tmp/.
+   - Never include secrets, credentials, or large binary dumps in the report.
+
+6. User-facing link
+   - In the chat response, include a clickable filesystem path to the generated HTML (markdown link to file path: ./tmp/...).
+   - If the environment doesn't support clickable file URIs, include the path and a short instruction to open it (example: `open ./tmp/filename.html`).
+
+7. When to prefer the report
+   - Use the HTML companion for long-running investigations, multi-command verification runs, or when results are easier to digest in a formatted artifact.
+
+8. Minimal examples
+   - Filename convention and example command to open the file.
+
+Do not replace the chat response with the HTML. The HTML is a companion artifact only and should not hold the only copy of crucial information.