Repository layout

Ask reads approved queries and guidance from a bitboard/ directory at the root of your connected GitHub repository.

You do not need to create this directory before connecting the repository. If it does not exist, the first pull request that adds a verified query or guidance file creates only the required path and files:

• a query creates bitboard/queries/<name>.yaml and bitboard/queries/<name>.sql; or
• guidance creates bitboard/guidance/<name>.md.

Git does not store empty directories, so BitBoard does not add unused folders.

bitboard/
  queries/
    revenue/
      monthly_revenue.yaml
      monthly_revenue.sql
  guidance/
    fiscal-calendar.md

Nested folders are optional and appear in Ask’s Workspace browser.

Query files

Every query has two files with the same name in the same folder:

• <name>.yaml contains metadata and parameters.
• <name>.sql contains one read-only query.

For example, monthly_revenue.yaml:

id: monthly_revenue
name: Monthly revenue
description: Recognized revenue through the selected date.
params:
  - name: as_of
    type: date
    description: Include revenue through this date.
    example: "2026-07-31"
version: 1
verified_by: Priya Raman
verified_at: 2026-08-01

And monthly_revenue.sql:

SELECT
  DATE_TRUNC('month', recognized_at) AS month,
  SUM(amount) AS revenue
FROM revenue
WHERE recognized_at <= $as_of
GROUP BY 1
ORDER BY 1

Query rules

• id and name are required.
• Every query ID must be unique across the repository.
• params, when present, is a list of named parameters.
• Every $placeholder in the SQL must match a declared parameter.
• Every declared parameter must be used by the SQL.
• SQL must contain one read-only statement beginning with SELECT or WITH.
• The SQL file must be valid UTF-8 text.

Guidance files

Guidance files are non-empty UTF-8 Markdown under bitboard/guidance/.

# Fiscal calendar

Weeks begin on Monday. Fiscal months close at 23:59 UTC on the final day.
Use recognized revenue unless a question explicitly asks for bookings.

Use guidance for definitions, caveats, naming conventions, and business rules. Do not put credentials or secrets in guidance.

Verification and sync

When a bitboard/ directory exists, BitBoard verifies it before making its content available to Ask. Verification checks the layout, query pairs, metadata, read-only SQL, parameter matching, and non-empty guidance.

Repository content is authoritative:

• adding or changing a valid file updates Ask on the next sync;
• removing a file revokes it from active use while preserving its history; and
• re-adding the file restores it on a later sync.

Changes proposed from BitBoard open as pull requests. After your team merges a pull request, sync the repository to make the approved content available.