{
  "markdown": "# Blank Files Website\n\nLaravel application that powers [blankfiles.com](https://blankfiles.com). Browse and download minimal valid blank files by type and category. File data and assets are served from the [filearchitect/blank-files](https://github.com/filearchitect/blank-files) repository via a configurable CDN.\n\n## Requirements\n\n- PHP 8.2+\n- Composer\n- Node.js 18+ (for Vite frontend build)\n\n## Installation\n\n```bash\ngit clone https://github.com/filearchitect/blankfiles-website.git\ncd blankfiles-website\ncomposer install\ncp .env.example .env\nphp artisan key:generate\n```\n\nSet `CDN_URL` in `.env` (see [Configuration](#configuration)). Then build the frontend and run the app:\n\n```bash\nnpm install && npm run build\nphp artisan serve\n```\n\nOr use [Laravel Herd](https://herd.laravel.com) with a `.test` domain.\n\n## Configuration\n\n| Variable        | Description                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `CDN_URL`       | **Required.** Base URL used to construct downloadable file URLs as `{CDN_URL}/files/{filename}`. Default: `https://raw.githubusercontent.com/filearchitect/blank-files/main` (set in [config/app.php](config/app.php)). |\n| `CATALOG_URL`   | Optional. Direct URL for the catalog JSON (`files/files.json`). Default is `https://raw.githubusercontent.com/filearchitect/blank-files/main/files/files.json` for freshness. |\n| `CACHE_ENABLED` | Optional. When `true`, the file list from the CDN is cached. TTL is controlled by `CATALOG_TTL_MINUTES` (default `10`). See [config/cache.php](config/cache.php) and [app/Services/FileService.php](app/Services/FileService.php).                                                                                                                                                                                           |\n| `CATALOG_TTL_MINUTES` | Optional. Cache TTL in minutes for the remote catalog when `CACHE_ENABLED=true`. Lower values reflect new formats sooner; higher values reduce CDN fetches. |\n| `API_KEYS` | Optional. Comma-separated API keys for higher-rate API clients (used by `X-API-Key` or `Authorization: Bearer ...`). |\n| `API_PUBLIC_RATE_LIMIT` | Optional. Public API requests/minute limit (default `30`). |\n| `API_KEY_RATE_LIMIT` | Optional. API-key requests/minute limit (default `300`). |\n| `API_USAGE_LOG_CHANNEL` | Optional. Logging channel for API usage analytics (default `api_usage`). |\n| `OPENPANEL_CLIENT_ID` | Optional. Enables OpenPanel web analytics script when set. |\n| `OPENPANEL_CLIENT_SECRET` | Optional. Reserved for server-side OpenPanel events (not exposed to browser script). |\n\n## Project structure\n\n| Path                                          | Purpose                                                      |\n| --------------------------------------------- | ------------------------------------------------------------ |\n| `app/Http/Controllers/FileController.php`     | Web: homepage, file detail page, download proxy.             |\n| `app/Http/Controllers/Api/FileController.php` | API: list all files, list files by type.                     |\n| `app/Services/FileService.php`                | Fetches catalog JSON (`CATALOG_URL`) and formats file URLs from `CDN_URL`. |\n| `routes/web.php`                              | Web routes (home, files show, download).                     |\n| `routes/api.php`                              | API v1 routes.                                               |\n| `resources/views/files/`                      | Blade views for file listing and file detail.                |\n\n## Deployment\n\nOn push to `main`, GitHub Actions:\n\n1. Builds the frontend (Vite) with `npm ci` and `npm run build`.\n2. SCPs `public/build/` to the Forge server.\n3. Triggers a Laravel Forge deployment.\n4. Runs `php artisan optimize:clear` on the server.\n\nRequired repository secrets:\n\n- `FORGE_SSH_HOST` — SSH host for the server.\n- `FORGE_SSH_USER` — SSH user (e.g. `forge`).\n- `SSH_PRIVATE_KEY` — Private key for SCP/SSH.\n- `FORGE_SERVER_ID` — Forge server ID.\n- `FORGE_SITE_ID` — Forge site ID.\n- `FORGE_API_KEY` — Forge deploy token.\n\nSee [.github/workflows/deploy.yml](.github/workflows/deploy.yml).\n\n---\n\n## For developers and bots\n\n### Base URL\n\nProduction: `https://blankfiles.com`. HTML and JSON are available; use `Accept: application/json` where applicable.\n\n### Web routes\n\n| Method | Path                                | Description                                                                                                                                |\n| ------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `GET`  | `/`                                 | Homepage: file list by category. Responds with JSON when `Accept: application/json`. Throttle: 30/min.                                     |\n| `GET`  | `/upload-testing`                   | Binary-focused landing page for upload testing intent, linking to high-demand file formats and categories.                                   |\n| `GET`  | `/files/{category}/{type}`          | SEO-friendly file detail page (e.g. `/files/document-spreadsheet/xlsx`). Constraints: `category`, `type` = `[A-Za-z0-9\\-]+`.               |\n| `GET`  | `/files/download/{category}/{type}` | Download proxy: streams the file with `Content-Disposition: attachment` (filename `blank.{type}` or `blank.{type}.zip`). Throttle: 60/min. |\n\n### API routes (prefix `api/v1`)\n\n| Method | Path                   | Response                                                                                                                                                        |\n| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `GET`  | `/api/v1/files`        | `{ \"files\": [ ... ], \"meta\": { \"version\", \"generated_at\", \"count\" } }`.                                                                                         |\n| `GET`  | `/api/v1/files/{type}` | Same schema, filtered by extension.                                                                                                                              |\n| `GET`  | `/api/v1/files/{category}/{type}` | Same schema with exactly one matching entry when found; `404` when missing.                                                                                   |\n| `GET`  | `/api/v1/status` | API health + aggregate catalog metrics (`file_count`, `type_count`, `category_count`) and upstream source info. |\n\n### Machine-friendly notes\n\n- The canonical file catalog schema is defined in the [blank-files](https://github.com/filearchitect/blank-files) repo: `files/files.json` (key `files`, array of `{ type, url, category, package? }`).\n- Download URLs: use the API `url` field for direct CDN access, or `GET /files/download/{category}/{type}` for a same-origin download with a predictable filename.\n- Conditional requests are supported on API responses and sitemap (`ETag`, `Last-Modified`).\n- Rate limits: public IP-based limits and optional API-key limits (`X-API-Key`).\n- API usage analytics are logged to `storage/logs/api-usage-*.log` (configurable channel).\n- Compatibility policy: [API policy](https://blankfiles.com/api-policy).\n- Web landing analytics for growth pages are logged to `storage/logs/web-traffic-*.log`.\n\n### Client snippets\n\n```bash\ncurl -sS \"https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx\" \\\n  -H \"Accept: application/json\" \\\n  -H \"X-API-Key: $BLANKFILES_API_KEY\"\n```\n\n```js\nconst res = await fetch(\"https://blankfiles.com/api/v1/files\", {\n  headers: { \"Accept\": \"application/json\", \"If-None-Match\": etag }\n});\nif (res.status === 304) {\n  // unchanged\n}\n```\n\n```python\nimport requests\nr = requests.get(\"https://blankfiles.com/api/v1/status\", timeout=20)\nr.raise_for_status()\nprint(r.json())\n```\n\n### Compatibility policy\n\n- URL versioning is stable under `/api/v1/*`.\n- Breaking changes require a new major API path version.\n- Deprecated endpoints are kept for at least 90 days before removal.\n- New fields may be added; clients should ignore unknown fields.\n\n---\n\n## Related\n\n- [filearchitect/blank-files](https://github.com/filearchitect/blank-files) — Source of truth for the file list and blank file assets.\n\n## MCP server (for agent marketplaces/registries)\n\nThis repository now includes a minimal MCP server that exposes Blank Files as tool calls.\n\n- Script: `scripts/mcp/blankfiles-mcp.mjs`\n- Run: `npm run mcp:server`\n- Optional env: `BLANKFILES_BASE_URL` (default: `https://blankfiles.com`)\n\nAvailable MCP tools:\n\n- `list_blank_files` — list files, optional filters (`category`, `type`, `limit`)\n- `files_by_type` — list entries by extension\n- `file_by_category_type` — deterministic single lookup by category + extension\n\nExample local MCP client config entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"blankfiles\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/blankfiles-website/scripts/mcp/blankfiles-mcp.mjs\"],\n      \"env\": {\n        \"BLANKFILES_BASE_URL\": \"https://blankfiles.com\"\n      }\n    }\n  }\n}\n```\n\nRegistry submission helpers:\n\n- Template metadata: `scripts/mcp/registry/server.json.template`\n- Publish checklist: `scripts/mcp/registry/PUBLISHING.md`\n\nPublished package workspace:\n\n- `packages/blankfiles-mcp` (publish as `@filearchitect/blankfiles-mcp`)\n\n## OpenClaw skill (ClawHub discoverability)\n\nThis repository includes an OpenClaw-ready skill bundle:\n\n- Skill path: `skills/blankfiles`\n- Skill entry: `skills/blankfiles/SKILL.md`\n- Publish guide: `skills/blankfiles/references/publish.md`\n\nTypical publish flow:\n\n```bash\nnpm i -g clawhub\nclawhub login\nclawhub publish ./skills/blankfiles \\\n  --slug blankfiles \\\n  --name \"Blank Files Gateway\" \\\n  --version 1.0.0 \\\n  --changelog \"Initial release\" \\\n  --tags latest\n```\n\n## License\n\nThis project is licensed under the MIT License.\n",
  "bytes": 10774,
  "sha": "bcd8451c0daa63e51f9c18ff01cdd692a97b6d8b8d0b4b573ef37b7d1af85dcc",
  "repo_slug": "filearchitect/blankfiles-website",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_filearchitect_blankfiles_mcp_ba1adaf8/readme"
}