# Postview AGENTS.md

Version: 1
Last-Updated: 2026-04-01
Canonical-URL: https://postview.ai/AGENTS.md

If you are preparing files for upload to Postview, return a finished static website bundle that is ready to zip and upload.

## Task
- Return the final static site files, not a source project that still needs a build step.
- Assume the user wants a ZIP-ready website that Postview can serve immediately.
- Optimize for a valid upload, not for framework-specific source layout.

## Required Output
- Put `index.html` at the top level of the final upload.
- Put the final site files at the top level of the final upload.
- Keep the ZIP file at or under `50MB`.
- Keep extracted contents at or under `100MB`.
- Keep total file count at or under `500`.
- Include mostly runtime site files and related static assets.
- Ensure every referenced local asset and page is included in the upload.
- Common allowed runtime file types include HTML, CSS, JS, MJS, JSON, XML, CSV, TXT, Markdown, common images, fonts, media, PDF, source maps, and web manifests.

## Do Not Return
- Do not return a React, Vite, Next, Astro, or similar source project unless you also provide the final built static output.
- Do not leave the site buried inside `dist/`, `build/`, or another subfolder.
- Do not include mostly scaffolding files such as configs, package-manager files, server code, tests, scripts, or secrets.
- Do not include nested ZIP files or files without useful runtime purpose.
- Do not rename binary files to the wrong extension.

## Recommended Structure

Valid single-page site:
```text
index.html
styles.css
app.js
images/
  hero.webp
```

Valid multi-page site:
```text
index.html
about/
  index.html
contact/
  index.html
assets/
  app.js
  styles.css
```

Risky mixed-root layout:
```text
README.md
dist/
  index.html
  assets/
    app.js
```

Use folder-style pages such as `about/index.html` when you want clean routes like `/about/`.

## Verify Before Returning
- `index.html` exists at the top level.
- The upload contains the final built site contents, not the parent project folder.
- Every local `src`, `href`, CSS `url()`, and script path points to an included file.
- Multi-page routes use folder-style pages such as `about/index.html` when appropriate.
- The archive stays within the size and file-count limits.
- Most files are runtime site assets, not development scaffolding.

## Current Fallbacks
- Postview may strip a single shared wrapper folder automatically. Do not rely on this as the primary contract.
- `index.htm` is accepted today, but prefer `index.html`.
- If there is exactly one root HTML file and it is not `index.html`, Postview may auto-use it as the homepage.
- If there are multiple root HTML files and none is `index.html`, the upload may succeed with a warning, but the root URL can return not found.

## Troubleshooting

### `NO_HTML_FILES`
You returned CSS, JS, or assets without any HTML page.
Fix: create a real top-level `index.html` and include the files it references.

### `NO_ROOT_INDEX`
You returned HTML files, but they are all inside subfolders.
Fix: move or create `index.html` at the top level of the upload.

### `ONLY_IMAGES`
You returned images without an HTML page to display them.
Fix: create `index.html` and render the gallery or image set there.

### `ONLY_NON_WEB`
You returned source files or data files without a web page.
Fix: generate a real static web page and package its runtime output.

### `MAJORITY_EXCLUDED`
Most files looked like non-site files and were excluded.
Fix: zip only the final runtime website output, not the whole project workspace.

### `MIME_MISMATCH`
A binary file extension did not match its actual content.
Fix: use the correct file and extension instead of renaming a different binary format.

## Tool Guidance
- ChatGPT, Claude, Cursor, and similar tools should return final ZIP-ready static output.
- If you use a framework, build or export it first, then zip the built output contents.
- Prefer concise file trees and complete final files over long explanations about how to build later.