`scalar project publish` silently excludes package-local `.gitignore`d files from the upload tarball → `FAILED_TO_PREPROCESS_PAGES`

What happens

When publishing a Scalar Docs project with scalar project publish, the CLI builds the upload tarball while applying the project-local .gitignore (the one next to scalar.config.json / package.json). Any file matched there is omitted from the upload.

This breaks a very common setup: an OpenAPI document that is generated at build time and intentionally gitignored, but still needs to be deployed. The generated spec is referenced by a page in scalar.config.json:

{ "type": "openapi", "filepath": "docs/api-reference/openapi.json", "title": "API reference" }

Because docs/api-reference/openapi.json is in the local .gitignore, the CLI leaves it out of the tarball. The build server then can't find the page source and fails with:

✔ FAILED_TO_PREPROCESS_PAGES

The dashboard build log shows the underlying error:

ERROR: error: ENOENT: no such file or directory, open '/app/docs-project/docs/api-reference/openapi.json'

Reproduce

1. A project whose OpenAPI spec is generated (e.g. from code) into docs/api-reference/openapi.json.
2. Add docs/api-reference/openapi.json to the project-local .gitignore (so the generated file isn't committed).
3. Reference it as a type: "openapi" page via filepath in scalar.config.json.
4. Generate the spec so it exists on disk, then scalar project publish --slug <slug> --preview.
5. Build fails with FAILED_TO_PREPROCESS_PAGES (ENOENT on the spec), even though the file is present locally.

Verified on @scalar/cli 1.9.2 and 2.0.1, Node 24.

Two issues, really

1. No way to keep a file gitignored locally but still deploy it. There's no .scalarignore, no include/files option, and no --include flag. A config-referenced page filepath arguably shouldn't be dropped by .gitignore at all.
2. The failure is opaque. Nothing tells you a referenced page file was excluded by .gitignore; you only get FAILED_TO_PREPROCESS_PAGES, and the ENOENT is only visible in the dashboard build log.

Suggestions

• Never exclude files explicitly referenced by a config filepath, or support a dedicated ignore/include mechanism (.scalarignore, config include, or --include).
• At minimum, emit a clear CLI error when a referenced page source is missing from the tarball (name the file and the reason).

Workaround

Move the ignore rule from the project-local .gitignore to a parent / monorepo-root .gitignore. The CLI only reads the project-local one (readGitIgnore(configDir)), so the file stays git-ignored while being included in the upload.