# Open questions and assumed answers

The application is functional with the assumptions below. These questions do
not block local use, but their answers determine the production repository and
security model.

## 1. What should enforce author permissions?

**Assumption implemented:** `.cms-access.yml` remains available for compatible
UI behaviour, but is explicitly advisory. GitHub collaborators, teams, branch
protection, environments, and reviews provide real authorization.

The original CMS enforced ACLs on a trusted FastAPI server using a verified
Keycloak identity and groups. A static application cannot reproduce that
guarantee: a user can modify its JavaScript or call GitHub directly with their
token.

Decision needed: keep advisory ACLs, remove them in favour of GitHub permissions,
or restore a small trusted authorization service.

## 2. Is manually entering a fine-grained PAT acceptable?

**Assumption implemented:** yes for the personal/static version. Tokens are
session-only unless the user opts into passphrase-encrypted IndexedDB storage.

Decision needed for a multi-user product: whether to add a GitHub App and a small
OAuth/token-exchange service. That improves onboarding and token lifetime but
makes the whole system no longer literally client-only.

## 3. Must access rules remain in a separate repository or branch?

**Assumption implemented:** content and mirrored access files use different
prefixes in the same repository and branch, allowing one atomic commit.

The original production CMS supported separate content and ACL repositories.
GitHub provides no atomic commit spanning repositories. Supporting that layout
would require sequential commits, rollback/repair logic, or a server-side
coordinator.

Decision needed: confirm the single-repository layout or specify the required
separate repository/branch contract.

## 4. Should publishing commit directly or open a pull request?

**Assumption implemented:** publish one non-forced commit directly to the
configured branch. Concurrent edits stop the operation and require an explicit
conflict choice.

Decision needed: whether production edits should instead create a CMS branch and
pull request. Pull requests fit protected repositories and approval workflows
better, but require additional GitHub permissions and UI.

## 5. How is GitHub Pages triggered?

**Assumption implemented:** a push normally triggers the repository's existing
Pages workflow. An optional workflow filename, ref, and input name can be
configured when manual `workflow_dispatch` is required.

Decision needed: the exact workflow filename, ref, and optional input contract
for SwingBig.Band. A token needs `Actions: write` only when the CMS dispatches it.

## 6. How exact must the preview be?

**Assumption implemented:** the preview uses a bundled CommonMark/GitHub-style
WebAssembly renderer with raw HTML disabled, followed by DOM sanitization.

The live SwingBig.Band site uses MkDocs Material, PyMdown extensions, emoji,
admonitions, blog routing, and theme-specific CSS. Running Python/MkDocs in a
browser WASM runtime would be much larger and would still need the site's Python
packages and theme assets.

Decision needed: whether fast safe Markdown preview is enough or whether exact
MkDocs output justifies shipping a Python/Pyodide toolchain and project assets.

## 7. Is StackEdit still required?

**Assumption implemented:** no. The PWA has a first-party editor, split view, and
WASM preview. Removing the hosted StackEdit iframe keeps private drafts on the
CMS origin and makes offline editing reliable.

Decision needed: whether to add an optional, clearly labelled StackEdit action.
Hosted StackEdit can read the selected document and cannot be part of a strict
offline/private threat model.

## 8. Should the CMS manage images and other assets?

**Assumption implemented:** it edits Markdown only, matching the original CMS.
The Git publishing layer can already create arbitrary blobs, but the UI rejects
non-Markdown content and applies a one-megabyte default limit.

Decision needed: permitted asset directories, file types, size limits, image
processing requirements, and whether binary drafts need OPFS preview support.

## 9. Where will the PWA be hosted?

**Assumption implemented:** any static HTTPS origin or subdirectory. The Vite
build uses relative asset paths and the manifest/service-worker scope follows the
configured base path.

Decision needed: the canonical production URL. A stable origin matters because
browser storage and encrypted credentials are origin-scoped; moving the CMS to a
new hostname or path does not migrate them automatically.