----------------------------------------------------------------------
This is the API documentation for the confquiz library.
----------------------------------------------------------------------


## Programmatic API

Load a validated configuration or export an attendee site from Python.



----------------------------------------------------------------------
This is the CLI documentation for the package.
----------------------------------------------------------------------

## CLI: confquiz

```

```

### confquiz init

```

```

### confquiz validate

```

```

### confquiz export

```

```

### confquiz preview

```

```

### confquiz present

```

```

### confquiz doctor

```

```

### confquiz firebase

```

```

### confquiz firebase scaffold

```

```

### confquiz sessions

```

```

### confquiz sessions list

```

```

### confquiz sessions release

```

```

### confquiz sessions clean

```

```


----------------------------------------------------------------------
This is the User Guide documentation for the package.
----------------------------------------------------------------------


## Getting started

### Conf Quiz

Conf Quiz runs a PDF presentation and anonymous audience questions on the same
timeline. A question appears immediately after its configured slide; when it is
finished, the presenter continues with the next page.

The speaker uses a local presenter view. Attendees use a static site on their
phones, usually hosted on GitHub Pages. Firebase carries room state, responses,
and published results between the two.

## What it is for

Conf Quiz is designed for conference talks, workshops, and community sessions
where the speaker wants feedback without turning the room into a competition.
It has no accounts, points, or leaderboard.

You can:

- poll the room with choice, range, rating, number, and ranking questions;
- collect free text and word-cloud responses with presenter moderation;
- mark a question as having a correct answer, then reveal it without awarding
  points;
- decide whether attendees see results live, after voting closes, after the
  reveal, or never;
- let each attendee switch independently between the light and dark interface;
- share the current PDF page to attendee devices; and
- restart or replace a room from the presenter computer.

## How a presentation runs

1. Prepare a PDF and a `quiz.yml` file.
2. Rehearse both screens with `confquiz preview`.
3. Export and publish the attendee site.
4. Start `confquiz present` on the speaker computer.
5. Show the QR code when the audience is ready to join.

The presenter service is not deployed. It uses Firebase Admin credentials on
the speaker's computer and sends only attendee-safe data to Firestore.

## Start here

- [Install Conf Quiz](user-guide/installation.html)
- [Build your first quiz](user-guide/first-quiz.html)
- [Configure Firebase](user-guide/firebase-setup.html)
- [Publish the attendee site](user-guide/deploy-attendee-site.html)

:::{.callout-note}
The local preview does not need Firebase. Use it while writing questions and
checking the slide order.
:::


### Installation

Conf Quiz supports Python 3.10 and newer. Node.js is not required when using the
published Python package; its browser files are already built.

## Install the command

With pip:

```bash
pip install conf-quiz
```

With uv, install it as an isolated command-line tool:

```bash
uv tool install conf-quiz
```

Check the installation:

```bash
confquiz --help
```

## Create a project-local environment

If you prefer to keep the package with a presentation repository:

```bash
uv init --bare my-talk
cd my-talk
uv add conf-quiz
uv run confquiz init .
```

Use `uv run confquiz ...` for the remaining commands in that repository.

## Files created by `init`

```bash
confquiz init my-talk
```

creates:

| File | Purpose |
|---|---|
| `quiz.yml` | Presentation, session, and question configuration |
| `sample-slides.pdf` | Twelve blank pages to make the example immediately runnable |
| `firebase.web.example.json` | Shape of the public Firebase web configuration |
| `.gitignore` | Excludes local Firebase configuration, credentials, and build output |

Replace `sample-slides.pdf` with your deck. Create the local Firebase file before
validating a live configuration:

```bash
cp firebase.web.example.json firebase.web.json
```

`firebase.web.example.json` is safe to commit because it contains placeholders.
`firebase.web.json` is ignored by Git and belongs to the speaker's Firebase
project.

`init` leaves existing files alone. Pass `--force` only when you intentionally
want to replace the generated examples.

## Presenter system requirements

For a live room, the presenter computer also needs:

- network access to Firebase;
- a Firebase Admin service-account JSON file or Application Default
  Credentials; and
- a modern browser for the presenter view.

The exported attendee site needs only static HTTPS hosting and a browser.

Continue with [Your first quiz](02-first-quiz.qmd).


### Your first quiz

Create a working directory:

```bash
confquiz init my-talk
```

Put your PDF at `my-talk/slides.pdf`, then replace `my-talk/quiz.yml` with a
small configuration:

```yaml
schema_version: 1

presentation:
  id: reliable-python
  title: "Reliable Python services"
  speaker: "Your name"
  public_url: "https://your-account.github.io/reliable-python/"
  slides:
    source: "slides.pdf"
  theme:
    preset: light
    accent: "#df4b2f"

firebase:
  web_config: "firebase.web.json"
  namespace: "confquiz"

session:
  show_results_on_presenter: false
  show_results_on_attendee_devices: true
  share_slides_with_attendees: false

questions:
  - id: first-poll
    after_slide: 2
    type: single_choice
    prompt: "Which failure do you plan for first?"
    options:
      - { id: network, label: "Network failure" }
      - { id: dependency, label: "Dependency failure" }
      - { id: bad-input, label: "Unexpected input" }
```

`after_slide: 2` puts the poll between PDF pages 2 and 3.

## Rehearse

```bash
confquiz preview my-talk/quiz.yml
```

The command prints two URLs:

- the presenter URL includes a local control token;
- the attendee URL ends in `/attend/?code=DEMO26`.

Open both. Use the arrow keys in the presenter view to move through the PDF.
After page 2, the question opens on both screens. Submit an attendee response,
then advance once to close voting and show results.

Preview stores everything in memory. It does not read or write Firestore and
is safe to restart as often as needed.

## Validate the files

Copy the generated example and replace every placeholder with the web
configuration from your own Firebase project:

```bash
cp my-talk/firebase.web.example.json my-talk/firebase.web.json
```

Then run:

```bash
confquiz validate my-talk/quiz.yml
```

Validation checks the YAML schema, Firebase metadata, PDF integrity, page
references, and remote-slide checksum when one is configured.

Next, [set up Firebase](10-firebase-setup.qmd) and
[publish the attendee site](12-deploy-attendee-site.qmd).



## Set up a live room

### Firebase setup

Conf Quiz uses Firebase only for live rooms. The public attendee app talks to
Firebase with the web SDK; the local presenter uses the Admin SDK.

## 1. Create the Firebase services

In one Firebase project:

1. Create the `(default)` Cloud Firestore database in Native mode.
2. Enable **Anonymous** in Authentication → Sign-in method.
3. Register a web app.
4. Copy `firebase.web.example.json` to the Git-ignored `firebase.web.json` beside
   `quiz.yml`.
5. Replace the placeholders with that web app's configuration object.

The file should contain the object itself, not the surrounding `<script>` tag:

```json
{
  "apiKey": "...",
  "authDomain": "your-project.firebaseapp.com",
  "projectId": "your-project",
  "storageBucket": "your-project.firebasestorage.app",
  "messagingSenderId": "...",
  "appId": "..."
}
```

Each speaker uses their own Firebase project and local `firebase.web.json`; Conf
Quiz does not provide a shared Firebase backend. The file identifies that
speaker's project but does not grant Admin access. The browser identifiers are
necessarily embedded in the exported attendee site so browsers can connect.
Firebase authorizes access through Authentication, Firestore Security Rules,
and App Check—not by hiding the web configuration. See Firebase's
[API key guidance](https://firebase.google.com/docs/projects/api-keys) for the
security model and key restrictions.

## 2. Add Firestore rules and indexes

Generate the files:

```bash
confquiz firebase scaffold my-talk
```

From the presentation directory, select the project and deploy:

```bash
npx firebase-tools login
npx firebase-tools use YOUR_PROJECT_ID
npx firebase-tools deploy --only firestore:rules,firestore:indexes
```

Do not leave Firestore in Test mode for a public event. The supplied rules deny
collection listing, keep raw responses private, and let each authenticated
attendee write only their own response while a question is open.

Keep `firebase.namespace` set to `confquiz`; the included rules use that fixed
collection prefix.

## 3. Create presenter credentials

Create a service account for the presenter and grant the least privilege needed
to read and write Firestore, such as `roles/datastore.user`. Download its JSON
key to the speaker computer.

Keep this file outside the repository. Start a room with an explicit path:

```bash
confquiz present quiz.yml --credentials /safe/path/firebase-admin.json
```

Alternatively set `GOOGLE_APPLICATION_CREDENTIALS` or use Application Default
Credentials.

## 4. Configure App Check

For a public attendee site:

1. Register a score-based reCAPTCHA Enterprise key for the attendee domain.
2. Register the web app with Firebase App Check.
3. Put the public site key in the quiz configuration:

   ```yaml
   firebase:
     web_config: "firebase.web.json"
     app_check_site_key: "your-public-site-key"
   ```

4. Deploy the attendee site and confirm valid requests in App Check metrics.
5. Enable enforcement for Firestore and Authentication after the rehearsal
   succeeds.

App Check reduces scripted abuse. It does not make an anonymous poll suitable
for voting, exams, or prizes.

## 5. Check the complete setup

```bash
confquiz doctor quiz.yml --credentials /safe/path/firebase-admin.json
```

`doctor` checks the web configuration, PDF, built browser assets, Admin
credential project, and a Firestore read.

:::{.callout-warning}
Never put the Admin JSON in the attendee export, a GitHub secret visible to pull
requests, the YAML file, or a browser environment variable.
:::


### Configuration

The configuration is strict YAML. Unknown fields, duplicate question IDs,
invalid answer keys, and unsupported combinations fail validation before the
presenter starts.

## Complete structure

```yaml
schema_version: 1

presentation:
  id: pycon-talk
  title: "A conference talk"
  speaker: "Speaker name"
  public_url: "https://speaker.github.io/pycon-talk/"
  slides:
    source: "slides.pdf"
    fetch_during_export: true
    # sha256: "64 hexadecimal characters for a remote PDF"
  theme:
    preset: light
    accent: "#df4b2f"
    background: "#101310"
    # logo: "logo.svg"

firebase:
  web_config: "firebase.web.json"
  app_check_site_key: null
  namespace: "confquiz"

session:
  join_code:
    mode: generated
    length: 6
  allow_answer_changes: true
  show_results_on_presenter: false
  show_results_on_attendee_devices: true
  share_slides_with_attendees: false
  minimum_public_responses: 1
  retention_hours: 168

questions: []
```

At least one question is required. A presentation can have up to 100.

`firebase.web_config` is resolved relative to `quiz.yml`. The generated project
uses the Git-ignored `firebase.web.json`, which each speaker fills with their
own Firebase web app configuration. Only the placeholder
`firebase.web.example.json` should be committed.

## Presentation

`presentation.id` becomes the stable Firestore presentation identifier. Use
lowercase letters, numbers, and hyphens, starting with a letter.

`presentation.public_url` is the deployed attendee-site URL. The presenter adds
the active room code to this URL when drawing the QR code. You can temporarily
override it from the presenter menu.

`slides.source` accepts a local path or an HTTP(S) URL. Local paths are resolved
relative to `quiz.yml`. Export freezes a remote PDF into the static site. Add a
`sha256` when the exact remote file must be reproducible. PDFs are limited to
100 MiB.

Available presenter theme presets are `light`, `dark`, `grey`, `navy`, `warm`,
`ocean`, and `forest`. The presenter may switch them during a talk; the browser
remembers the choice for that presentation.

## Join codes

Generated codes are the default and work well for rehearsals and repeated
events:

```yaml
session:
  join_code:
    mode: generated
    length: 6
```

For a code printed in event material:

```yaml
session:
  join_code:
    mode: manual
    value: PYCON26
```

Manual codes use 4–12 characters from `A–Z` and `2–9`. Starting a second live
room with the same active code will fail instead of silently taking it over.

## Result and slide defaults

`show_results_on_presenter` controls the open-voting default. Results always
appear in the presenter when voting closes or an answer is revealed.

`show_results_on_attendee_devices` is a session-wide switch. A question's own
visibility still decides when results appear. `minimum_public_responses` keeps
an aggregate off attendee screens until enough answers exist.

`share_slides_with_attendees` sets the initial state. The presenter can toggle
slide sharing from the options menu.

## Retention

`retention_hours` records the intended room lifetime. On Firebase plans without
TTL deletion, run `confquiz sessions clean` yourself; see
[Session maintenance](31-session-maintenance.qmd).

For question fields and valid answers, see
[Question types](21-question-types.qmd).


### Deploy the attendee site

The attendee app is static HTML, CSS, JavaScript, and the presentation PDF. It
can run on GitHub Pages or another HTTPS static host. The presenter remains on
the speaker computer.

## Export

```bash
confquiz validate quiz.yml
confquiz export quiz.yml --output site
```

The output includes `.nojekyll` and uses relative asset paths, so it works under
a GitHub Pages repository path. The export contains the Firebase web
configuration and attendee-safe presentation data. It does not contain the
Admin credential, answer keys, or the complete question schedule.

## Publish a presentation repository

Set the final address in `quiz.yml`:

```yaml
presentation:
  public_url: "https://your-account.github.io/my-talk/"
```

In the presentation repository, create an Actions secret named
`FIREBASE_WEB_CONFIG` and paste the complete JSON object from your own Firebase
web app. The workflow creates the ignored `firebase.web.json` only on the build
runner.

Add this workflow as `.github/workflows/pages.yml` in the presentation
repository:

```yaml
name: Deploy attendee site

on:
  workflow_dispatch:
  push:
    branches: [main]
    paths:
      - "quiz.yml"
      - "slides.pdf"
      - "uv.lock"
      - "pyproject.toml"
      - ".github/workflows/pages.yml"

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: attendee-pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.13"
      - uses: astral-sh/setup-uv@v7
      - run: uv sync --locked
      - name: Write speaker Firebase web config
        env:
          FIREBASE_WEB_CONFIG: ${{ secrets.FIREBASE_WEB_CONFIG }}
        run: |
          test -n "$FIREBASE_WEB_CONFIG"
          printf '%s' "$FIREBASE_WEB_CONFIG" > firebase.web.json
      - run: uv run confquiz export quiz.yml --output site
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v5
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5
```

In the GitHub repository, open **Settings → Pages** and choose **GitHub
Actions** as the source.

The secret prevents the Firebase configuration from being committed or reused
by another presentation repository. It is not a substitute for Firestore Rules
or App Check: the exported attendee site necessarily contains these browser
identifiers.

## Authorized domains

Add the attendee hostname to Firebase Authentication's authorized domains and
to the reCAPTCHA Enterprise/App Check configuration. For a project page, the
hostname is `your-account.github.io`; the repository path is not part of the
authorized-domain entry.

## Check the homepage before the event

Open the deployed URL without a room code. It should show PDF page 1 as the main
content and a short note that the page becomes interactive when the speaker
opens a room.

Start `confquiz present`, reload the deployed page, and confirm that:

- the join panel appears above the slide;
- the QR code opens the deployed URL with `?code=...`;
- an attendee can submit one answer; and
- closing voting updates results on both screens as configured.

The presenter writes a short-lived presentation heartbeat. If the presenter
process disappears, the public homepage stops advertising the room after the
heartbeat expires.

## Local network check

You may serve an export on the conference network:

```bash
python -m http.server 8766 --bind 0.0.0.0 --directory site
```

Use the computer's LAN address in `presentation.public_url`, not `127.0.0.1`.
Some Firebase and App Check features require HTTPS, so GitHub Pages is the safer
final rehearsal target.



## Run the presentation

### Presenter workflow

Run a final setup check before going on stage:

```bash
confquiz doctor quiz.yml --credentials /safe/path/firebase-admin.json
```

Start the presenter:

```bash
confquiz present quiz.yml --credentials /safe/path/firebase-admin.json
```

By default it listens only on `127.0.0.1:8765`. The command prints a presenter
URL containing a random control token. Do not share that URL; show the attendee
QR code from inside the presenter instead.

## Timeline

The presenter starts on PDF page 1. Slides and questions are one ordered
timeline:

```text
slide 1 → slide 2 → question after slide 2 → slide 3
```

For an open question, advancing once closes voting and shows results. If the
question has `correct`, advancing again reveals the answer. The following
advance continues to the next slide.

## Keyboard controls

| Key | Action |
|---|---|
| Right arrow, Space, Page Down | Move forward |
| Left arrow, Page Up | Move back |
| `J` | Show or hide the joining information |
| `F` | Enter or leave fullscreen |
| `H` | Hide or restore the bottom controls while fullscreen |

When controls are hidden in fullscreen, small controls remain at the bottom
right. During open voting, one of them opens the live results. Arrow-key
navigation continues to work.

## Joining information

The link control shows a thin, sticky joining strip. The QR control opens a
larger room screen that uses the configured attendee URL and current code.

If the attendee site moved after the YAML was exported, open the options menu
and set a temporary attendee-site URL. The displayed link and QR code update
without changing the file.

## Results

The chart control shows or hides live results while voting is open. Participant
and answer counts remain available to the presenter. Closing voting or revealing
an answer always shows results and statistics, even if live results were hidden.

Attendee visibility is separate. Configure it per question and use the session
switch to disable results on all attendee devices when needed.

## Slides on attendee devices

Slide sharing starts from the session default. The toggle is in the options
menu. When enabled, attendee devices follow the active PDF page and questions
replace the slide automatically. The attendee can expand the shared slide to
fullscreen on a phone.

## Session actions

Use the session menu to:

- clear answers for the current question;
- restart the presentation at page 1 and clear the room;
- end the active room;
- generate a new room and join code; or
- change the attendee-site URL for the current presenter process.

Reset and restart actions cannot be performed by attendees. They are handled by
the local Admin connection.

## Resume after a computer restart

If the presenter computer or process stops during a live room, restart it with the existing join code:

```bash
confquiz present quiz.yml \
  --resume PYAU26 \
  --credentials /safe/path/firebase-admin.json
```

Conf Quiz reconnects to the same Firestore session and restores its last synchronized slide or question state, responses, moderation decisions, participant listener, and join code. Attendee browsers that stayed open remain attached to that session.

Use the same `quiz.yml`, PDF, Firebase project, and presentation ID. Resume fails if the room ended, expired, belongs to another presentation, or was created from different quiz configuration. Stop the old presenter process before resuming. Do not run `sessions release` first because release ends the room mapping.

If the computer stopped before the most recent navigation write reached Firebase, recovery starts from the last synchronized timeline position. Move forward or back once to return to the intended slide.

## Before the session

- Keep the presenter process running when opening the browser.
- Close unused preview tabs so that keyboard focus is unambiguous.
- Test the QR code using mobile data as well as venue Wi-Fi.
- Keep a PDF viewer ready as a fallback presentation path.
- End or replace test rooms before the audience arrives.


### Question types

Every question needs a unique `id`, a PDF page in `after_slide`, a `type`, and a
`prompt`. Questions that use choices also need stable option IDs.

## Single choice

```yaml
- id: preferred-runtime
  after_slide: 2
  type: single_choice
  prompt: "Which runtime do you use most?"
  options:
    - { id: cpython, label: "CPython" }
    - { id: pypy, label: "PyPy" }
    - { id: other, label: "Another runtime" }
  correct: cpython
```

`correct` is optional and must be one option ID.

## Multiple choice

```yaml
- id: quality-checks
  after_slide: 4
  type: multiple_choice
  prompt: "Which checks run before merge?"
  max_selections: 3
  options:
    - { id: tests, label: "Tests" }
    - { id: lint, label: "Lint" }
    - { id: types, label: "Type checks" }
    - { id: security, label: "Security scan" }
  correct: [tests, lint, types]
```

The answer may be changed while voting is open when
`session.allow_answer_changes` is true.

## Yes or no

```yaml
- id: uses-type-hints
  after_slide: 5
  type: yes_no
  prompt: "Does your production code use type hints?"
  correct: "yes"
```

The valid correct values are the strings `yes` and `no`.

## Slider

```yaml
- id: confidence
  after_slide: 6
  type: slider
  prompt: "How confident are you with async Python?"
  min: 0
  max: 10
  step: 1
  labels: { min: "New to it", max: "Very confident" }
```

Slider defaults are 0–10 with a step of 1. A numeric `correct` value is
supported when it follows the configured range and step.

## Rating

```yaml
- id: pace
  after_slide: 7
  type: rating
  prompt: "How is the pace?"
  min: 1
  max: 5
  step: 1
```

Rating defaults are 1–5 with a step of 1.

## Number

```yaml
- id: timeout
  after_slide: 8
  type: number
  prompt: "What timeout would you choose in milliseconds?"
  min: 1
  max: 10000
  step: 1
  correct: { value: 500, tolerance: 50 }
```

Number questions require `min` and `max`. A correct answer may be a single
number or an object with `value` and a non-negative `tolerance`.

## Ranking

```yaml
- id: priorities
  after_slide: 9
  type: ranking
  prompt: "Rank these production priorities."
  options:
    - { id: reliability, label: "Reliability" }
    - { id: speed, label: "Delivery speed" }
    - { id: cost, label: "Cost" }
```

Attendees move choices up and down. Ranking questions do not support a correct
answer.

## Free text

```yaml
- id: next-step
  after_slide: 10
  type: free_text
  prompt: "What will you try next?"
  max_length: 240
  placeholder: "One practical next step"
  results:
    display: cards
    attendee_visibility: after_close
```

Text answers enter the presenter moderation queue. They are not included in
public results until approved.

## Word cloud

```yaml
- id: takeaway
  after_slide: 11
  type: word_cloud
  prompt: "Describe your main takeaway in a few words."
  max_length: 80
  results:
    display: word_cloud
    attendee_visibility: after_close
```

Word-cloud entries use the same moderation path as free text.

## Result settings

Every type accepts a `results` object:

```yaml
results:
  display: bars
  attendee_visibility: live
  show_mean: true
  show_median: true
```

Available displays are `bars`, `histogram`, `summary`, `ranking`, `cards`, and
`word_cloud`. Conf Quiz chooses a suitable display when it is omitted.

Attendee visibility can be:

| Value | Result timing |
|---|---|
| `live` | While voting is open and afterwards |
| `after_close` | After voting closes |
| `after_reveal` | Only after a configured correct answer is revealed |
| `never` | Presenter only |

See [Results and moderation](22-results-and-moderation.qmd) for session-wide
controls and privacy behavior.


### Results and moderation

Presenter results and attendee results have separate controls. This lets the
speaker watch the room without publishing a changing chart to every phone.

## Presenter behavior

`session.show_results_on_presenter` sets the initial behavior while voting is
open. The chart button can override it for the current question.

Conf Quiz always shows the participant count to the presenter. When voting
closes or a correct answer is revealed, the presenter view always shows:

- joined participants;
- submitted answers; and
- the result visualization.

This closed-voting behavior is not affected by hiding live results.

## Attendee behavior

The session switch must be on:

```yaml
session:
  show_results_on_attendee_devices: true
```

Then each question selects `live`, `after_close`, `after_reveal`, or `never`.
If the session switch is off, no question publishes results to attendee
screens.

Use a response threshold to avoid drawing conclusions from one early answer:

```yaml
session:
  minimum_public_responses: 5
```

The presenter still sees the actual counts below the threshold.

## Correct answers

Adding `correct` creates a reveal step for supported question types. It does not
create points, a score, or a leaderboard. The exported attendee bundle does not
contain the answer key; the presenter publishes it only during the reveal
phase.

## Text moderation

Free-text and word-cloud responses are private when submitted. In the
presenter moderation drawer, approve entries that may appear publicly and hide
anything unsuitable.

Moderation decisions are stored separately from raw responses. The public
aggregate contains only approved text. Attendee clients cannot read the raw
response collection or moderation records.

For sensitive topics, set `attendee_visibility: never` and discuss selected
responses verbally instead of publishing them.

## Interpreting counts

The participant count represents anonymous authenticated browser profiles that
joined the room. It is not an attendance register. The answer count is the
number of response documents for the active question.

An attendee who reloads in the same browser profile keeps the same anonymous
Firebase identity. Clearing site data, using another browser, or using another
device creates another identity.



## Operations

### Security

Conf Quiz separates the trusted presenter from the public attendee app. The
presenter owns the room and answer keys; attendee clients receive only the data
needed for the current screen.

## Trust boundaries

| Component | Runs where | Credential |
|---|---|---|
| Presenter service | Speaker computer | Firebase Admin credential |
| Presenter browser | Speaker computer | Random local control token |
| Attendee app | Static host and attendee browser | Firebase web config + Anonymous Auth |
| Firestore | Firebase | Security Rules and optional App Check enforcement |

The Firebase web config and App Check site key are public identifiers. The
Admin service-account JSON is a secret.

## Firestore rules

The included rules enforce these boundaries:

- presentation status permits one exact public read and does not expose a room
  code or session ID;
- join-code documents allow exact reads, never collection listing;
- room data requires Anonymous Authentication;
- an attendee writes only the response document matching their Auth UID;
- a write is accepted only for the active, open question;
- answer types, option IDs, lengths, and numeric ranges are checked;
- raw responses and moderation records are not readable by attendees; and
- result aggregates are presenter-authored and read-only to attendee clients.

Deploy the supplied rules before the attendee URL is public. Firebase Test mode
is not an acceptable event configuration.

## Local presenter token

The presenter URL contains a fresh random token. Requests also pass browser
origin checks. The server binds to `127.0.0.1` unless you explicitly select
another host.

If you bind the presenter to `0.0.0.0`, anyone on the local network can reach
the port and attempt to access it. Keep the token private and use a trusted
network. The attendee static site does not require the presenter port to be
public.

## App Check

App Check helps Firebase distinguish your attendee app from unapproved scripts.
Enable it after checking metrics with the deployed site. A wrong hostname or
site key can lock out every attendee, so do not turn on enforcement for the
first time on stage.

## Intended use

Anonymous Auth makes casual duplicate submissions less convenient; it does not
prove identity or one-person-one-vote. Conf Quiz is not designed for:

- elections;
- graded assessment;
- prize-bearing competitions;
- confidential surveys; or
- regulated or high-stakes decisions.

For a conference poll, tell attendees what will be displayed, avoid collecting
personal information, and clean up old rooms after the stated retention period.

## Reporting a vulnerability

Report security issues privately to the maintainer. Do not include live Admin
credentials, attendee data, or an exploitable public room in a GitHub issue.


### Session maintenance

Conf Quiz does not depend on paid Firestore TTL deletion. The presenter can inspect, resume, release, and remove sessions with the Admin SDK.

## List recent rooms

```bash
confquiz sessions list quiz.yml --credentials /safe/path/firebase-admin.json
```

The output includes the session ID, join code, status, and creation time. Listing
requires the same Firebase project and namespace as the presentation.

## Release one join code

Ending a room from the presenter releases its join code immediately. Use the targeted release command when you want to discard one stale room while keeping its stored data:

```bash
confquiz sessions release PYAU26 \
  --config quiz.yml \
  --credentials /safe/path/firebase-admin.json
```

When `quiz.yml` and the Firebase Admin credentials are already available through the default paths, the short form is enough:

```bash
confquiz sessions release PYAU26
```

The command verifies that the code belongs to the presentation in `quiz.yml`, marks the linked room ended, and releases its mapping. It keeps the session and response documents for later inspection or cleanup. Do not release a room that you intend to resume after a presenter-computer restart. Use `confquiz present quiz.yml --resume PYAU26` instead.

## Delete expired rooms

Delete sessions older than seven days:

```bash
confquiz sessions clean quiz.yml \
  --older-than 168 \
  --credentials /safe/path/firebase-admin.json
```

The operation permanently deletes matching session documents and their nested
question, response, participant, aggregate, and moderation data. It does not
delete the PDF or exported attendee site.

Set the command threshold to match `session.retention_hours` in `quiz.yml`.

:::{.callout-warning}
`sessions clean` is permanent. List rooms first and confirm that the command is
pointing at the intended Firebase project.
:::

## Prepare for another run

During rehearsal, use the presenter session menu to restart the active room or
generate a new join code. Before the real session:

1. end the final test room;
2. start a new room;
3. scan its QR code from another device;
4. submit and clear one test answer; and
5. leave the presenter process running.

A manual join code can be reused after its earlier room is ended. A generated
code avoids stale printed links and accidental reuse.

## Firebase usage

Every connected room uses Firestore document reads for live listeners and
writes for joins, answers, state changes, and aggregates. Cleaning old data does
not reduce reads already billed, but it limits retained audience data and keeps
manual inspection manageable.

For an event of up to 100 attendees, rehearse with the same number of questions
and result settings you plan to use. Check current Firebase quotas and billing
in the Firebase console before the event because plan limits can change.


### Troubleshooting

Start with the checks that do not change live data:

```bash
confquiz validate quiz.yml
confquiz doctor quiz.yml --credentials /safe/path/firebase-admin.json
```

## The attendee page says no room is open

Check that:

- `confquiz present` is still running;
- the presenter created a live room rather than opening only `preview`;
- the exported site and presenter use the same Firebase `projectId`;
- `presentation.id` matches the version used for export; and
- the system clock on the presenter computer is correct.

The public room notice uses a short-lived heartbeat. It is expected to disappear
after the presenter process stops.

## A room code is rejected

- Enter the full code without spaces. Codes exclude `0`, `1`, `I`, and `O`.
- Confirm the QR code points at the currently deployed attendee URL.
- End stale rooms before reusing a manual code.
- Check that Anonymous Authentication is enabled.
- Look for App Check enforcement errors in the browser console and Firebase
  metrics.

## Answers cannot be submitted

The question must be the active timeline item and voting must still be open.
If every attendee is affected, verify the deployed Firestore rules and the
authorized attendee hostname. If one browser is affected, try reloading before
clearing site data; clearing it creates a new anonymous identity.

## Results do not appear

For presenter results, close voting or use the chart control while voting is
open. Closed and reveal screens always show results.

For attendee results, check all three gates:

1. `session.show_results_on_attendee_devices` is true;
2. the question's `attendee_visibility` allows the current phase; and
3. `minimum_public_responses` has been reached.

Text and word-cloud entries must also be approved by the presenter.

## Slides do not load

Run `confquiz validate` and check the PDF outside Conf Quiz. Password-protected,
damaged, or unusually encoded PDFs may fail. For remote slides, confirm the URL
is reachable during export and update `sha256` only after verifying the new
file.

If the PDF works in preview but not on the attendee site, inspect the browser
network panel for the PDF and PDF.js worker paths. Re-export instead of copying
individual files into an old site directory.

## The QR code points to localhost

Set `presentation.public_url` to the deployed attendee URL, then restart the
presenter. A temporary override is also available in the presenter options
menu. `127.0.0.1` always means the device opening the URL, so it cannot be an
attendee address.

## The presenter port is busy

Choose another port:

```bash
confquiz present quiz.yml --port 8877 --credentials /safe/path/firebase-admin.json
```

The control token and presenter URL are regenerated for that process.

## Credential project mismatch

Conf Quiz compares the Admin credential's `project_id` with the Firebase web
configuration. Use a key from the same project; do not bypass the check by
copying identifiers between files.

## Get command help

```bash
confquiz COMMAND --help
confquiz firebase --help
confquiz sessions --help
```

The [CLI reference](../reference/cli/index.html) documents every option.



## Contributing

### Development

Conf Quiz is a Python package with browser source files in the same repository.
The wheel includes prebuilt JavaScript, CSS, templates, Firestore scaffolding,
and PDF.js assets.

## Set up the repository

```bash
uv sync --extra dev
npm install
npm run build
```

Use uv for Python dependency changes so that `uv.lock` remains the source of
the resolved environment.

## Run the test suites

```bash
uv run pytest
npm test
```

Run the Firestore Security Rules suite with Java and the Firebase Emulator
Suite available:

```bash
npm run test:rules
```

Lint Python source and tests:

```bash
uv run ruff check src tests scripts
```

When browser source changes, run `npm run build` and commit both the source and
generated package assets. The Python package must remain usable without Node.js.

## Documentation

The docs use Great Docs and require Python 3.11 or newer plus Quarto:

```bash
uv sync --group docs
uv run --group docs great-docs build
uv run python scripts/verify-docs.py great-docs/_site
```

All authored documentation pages live under `docs/`. Files in `docs/guide/`
form the user guide; `docs/examples/` is a separate Examples section.

To inspect the rendered output:

```bash
python -m http.server 8770 --bind 127.0.0.1 --directory great-docs/_site
```

The repository's GitHub Pages workflow publishes this documentation. A
presentation repository uses the separate attendee workflow in
[Deploy the attendee site](12-deploy-attendee-site.qmd).

## Build the package

Build outside the attendee export directory:

```bash
uv build --out-dir build-artifacts
```

Before a release, install the wheel into a clean environment and check:

```bash
confquiz --help
confquiz init /tmp/conf-quiz-check
confquiz preview /tmp/conf-quiz-check/quiz.yml
```

Package publication and GitHub release creation are maintainer operations and
are not performed by the documentation workflow.

## Public names

- Distribution and repository: `conf-quiz`
- Python import package: `confquiz`
- Command: `confquiz`

Keeping the import and command free of punctuation follows normal Python and
shell naming conventions.