@web42/cli 0.1.6 → 0.1.8

package/skills/web42-publish-prep/references/web42-folder.md

@@ -0,0 +1,120 @@
+# The `.web42/` Folder
+
+The `.web42/` directory in your agent workspace is the metadata and sync hub for the Web42 marketplace. It is created automatically by `web42 init`.
+
+## Structure
+
+```
+.web42/
+├── marketplace.json     # Pricing, license, tags
+├── resources.json       # Metadata for resource files
+├── sync.json            # Sync state (auto-managed, do not edit)
+├── avatar.png           # Agent profile image (optional)
+├── resources/           # Screenshots, videos, documents
+│   ├── screenshot-1.png
+│   └── demo.mp4
+└── dist/                # Pack output (auto-generated by web42 pack)
+    ├── AGENTS.md
+    ├── IDENTITY.md
+    ├── manifest.json
+    └── ...
+```
+
+## Files You Edit
+
+### `marketplace.json`
+
+Controls pricing, licensing, and discoverability on the marketplace.
+
+- Created by `web42 init` with defaults.
+- Edit manually or with agent assistance.
+- Synced to/from the remote on push/pull.
+- See `references/marketplace-config.md` for the full field reference.
+
+### `resources.json`
+
+Describes the resource files (screenshots, videos, documents) in the `resources/` subdirectory.
+
+- JSON array of `ResourceMeta` objects.
+- Each entry maps a file in `resources/` to a title, description, type, and display order.
+- See `references/resources-guide.md` for the schema and guidance.
+
+### `avatar.{png,jpg,jpeg,webp,svg}`
+
+The agent's profile image, shown on the marketplace listing and search results.
+
+- Only one avatar file should exist (the CLI picks the first match by extension priority: png, jpg, jpeg, webp, svg).
+- Recommended: 400x400 or larger, square aspect ratio.
+- Uploaded to the server on `web42 push`.
+
+### `resources/`
+
+Directory containing the actual resource files referenced by `resources.json`.
+
+- Drop images, videos, or PDFs here.
+- Filenames must match the `file` field in `resources.json`.
+
+## Files You Should NOT Edit
+
+### `sync.json`
+
+Tracks the sync state between your local workspace and the remote database.
+
+```json
+{
+  "agent_id": "0c4cc49e-...",
+  "last_remote_hash": "7b1d3ecf...",
+  "last_local_hash": "d9a10b8a...",
+  "synced_at": "2026-03-17T03:54:46.124Z"
+}
+```
+
+- **Auto-managed** by `web42 push`, `web42 pull`, and `web42 sync`.
+- Editing this file manually will break change detection.
+- Safe to delete if you want to force a full re-sync (next push/pull will recreate it).
+
+### `dist/`
+
+The pack output directory, generated by `web42 pack` or automatically during `web42 push`.
+
+- Contains the processed, distributable version of your agent files.
+- **Auto-generated** — do not edit files here directly.
+- Excluded from the pack itself (no recursion).
+
+## Git Integration
+
+Add `.web42/sync.json` and `.web42/dist/` to `.gitignore` since they are auto-generated:
+
+```gitignore
+.web42/sync.json
+.web42/dist/
+```
+
+Keep these in version control:
+
+- `.web42/marketplace.json`
+- `.web42/resources.json`
+- `.web42/avatar.*`
+- `.web42/resources/`
+
+## `.web42ignore` (Workspace Root)
+
+Not inside `.web42/` — lives at the workspace root alongside `manifest.json`.
+
+- Created by `web42 init` with sensible defaults (IDE dirs, env files, test folders, drafts).
+- Glob patterns, one per line. Lines starting with `#` are comments.
+- Controls which files are excluded when running `web42 pack` or `web42 push`.
+- Use `web42 pack --dry-run` to verify what gets included/excluded.
+- See `references/file-hygiene.md` for full details.
+
+Keep `.web42ignore` in version control so the ignore rules travel with the project.
+
+## Sync Lifecycle
+
+```
+web42 init     → Creates .web42/, marketplace.json, resources.json, .web42ignore
+web42 pack     → Generates .web42/dist/ from workspace files (respects .web42ignore)
+web42 push     → Sends snapshot (manifest + README + marketplace + files + avatar + resources) to remote
+web42 pull     → Fetches remote snapshot, writes to local files
+web42 sync     → Shows local vs remote hash comparison without changing anything
+```