AJTU - Agent Instructions

Guidance for contributing to "A Journey Through the Unknown". This repository contains the React front end and Firebase Cloud Functions that power the playable sci-fi adventure.

Tech Stack and Tooling

React 18 with TypeScript (via Create React App)
Firebase Hosting, Functions, and Storage rules
Chakra UI component library
Jest (React Testing Library on the web app, Jest in Cloud Functions)
Prettier with a 120 character print width (
```
.prettierrc
```
)
Volta pins Node.js 22.11.0; stay on Node 22 when working in this repo
Package manager: npm (one lock file per project directory)

Project Layout

.
├── website/                     # React application, Firebase config, hosting assets
│   ├── public/                  # Static assets served by CRA
│   ├── src/                     # Front-end source (components, pages, routes)
│   ├── functions/               # Firebase Cloud Functions (TypeScript + Jest)
│   ├── firebase.json            # Firebase hosting and emulator configuration
│   ├── storage.rules            # Firebase Storage security rules
│   └── package.json             # CRA scripts (start, build, test, deploy)
├── README.md                    # High-level project overview and deployment notes
├── AGENTS.md                    # Coding agent guidance (this document)
└── .prettierrc                  # Repository-wide formatting rule (printWidth 120)

Commands must be executed inside

website

website/functions

; there is no root-level

package.json

Setup

Use Node 22 (Volta will pin automatically; otherwise install via nvm).

Install front-end dependencies:

cd website
npm install

Install Cloud Functions dependencies:

cd website/functions
npm install

Install the Firebase CLI (
```
npm install -g firebase-tools
```
) and authenticate with
```
firebase login
```
before deploying or running emulators.

Environment and Secrets

Copy

website/functions/.env-template

.env

and fill in

OPENAI_API_KEY

and

SENTRY_DSN

for local or production use.

For local Cloud Function emulation or image uploads, add your Firebase service account key at
```
website/functions/src/service-account-key.json
```
(template provided in the same folder).
Never commit populated
```
.env
```
files or service account keys.

Development Commands

Website (

website/

)

```
npm start
```
- run the CRA development server.
```
npm run build
```
- create a production build (required before deploys).
```
npm test
```
- run Jest tests via CRA (watch mode by default).
```
npm run deploy
```
- deploy Hosting and Functions. Runs
```
npm run build
```
first.

Cloud Functions (

website/functions/

)

```
npm run build
```
- compile TypeScript to
```
build/
```
.
```
npm run serve
```
- build then start the Firebase emulator for Functions.
```
npm run test
```
- execute Jest unit tests.

npm run deploy

- deploy Functions only (

firebase deploy --only functions

Keep strict TypeScript checks passing in both projects (

tsconfig

files enable strict mode).

Firebase Workflow Notes

Hosting and Functions share the Firebase project declared in
```
.firebaserc
```
inside
```
website/
```
.
Update
```
website/storage.rules
```
when altering storage behavior and deploy with
```
firebase deploy --only storage
```
.
Favor the local emulator (
```
npm run serve
```
) during development to avoid hitting production resources.

Validation Checklist

Run these before sharing work:

```
cd website && npm run build
```
```
cd website && npm test
```
```
cd website/functions && npm run build
```
```
cd website/functions && npm test
```
Format touched files with Prettier:
```
npx prettier --write <files>
```

Code Style and Conventions

Keep related statements together and separate distinct steps with blank lines; clarity beats compactness.
Prefer small, composable React components. Co-locate component-specific helpers alongside the component.
Use TypeScript interfaces or types, not
```
any
```
, unless interacting with untyped external data. Document assumptions with short comments when necessary.
Prefix all type-only imports with the
```
type
```
keyword (for example,
```
import type { Foo } from './Foo';
```
).
Stick to named exports. Avoid default exports unless required by third-party APIs.
Use template strings for combining dynamic text; avoid string concatenation with
```
+
```
.
Define React component prop interfaces separately and destructure inside the function body for readability.
Maintain file sizes under roughly 400 lines. Extract utilities or components when they grow large.
Do not commit build artifacts or secrets.

Helpful References

Project overview and deployment steps:
```
README.md
```
Firebase CLI documentation: https://firebase.google.com/docs/cli
Create React App documentation: https://create-react-app.dev/docs/getting-started/

Mirror existing patterns in

website/src

and

website/functions/src

when extending the codebase. When unsure, ask for clarification rather than guessing.

AJTU - Agent Instructions

Guidance for contributing to "A Journey Through the Unknown". This repository contains the React front end and Firebase Cloud Functions that power the playable sci-fi adventure.

Tech Stack and Tooling

React 18 with TypeScript (via Create React App)
Firebase Hosting, Functions, and Storage rules
Chakra UI component library
Jest (React Testing Library on the web app, Jest in Cloud Functions)
Prettier with a 120 character print width (
```
.prettierrc
```
)
Volta pins Node.js 22.11.0; stay on Node 22 when working in this repo
Package manager: npm (one lock file per project directory)

Project Layout

.
├── website/                     # React application, Firebase config, hosting assets
│   ├── public/                  # Static assets served by CRA
│   ├── src/                     # Front-end source (components, pages, routes)
│   ├── functions/               # Firebase Cloud Functions (TypeScript + Jest)
│   ├── firebase.json            # Firebase hosting and emulator configuration
│   ├── storage.rules            # Firebase Storage security rules
│   └── package.json             # CRA scripts (start, build, test, deploy)
├── README.md                    # High-level project overview and deployment notes
├── AGENTS.md                    # Coding agent guidance (this document)
└── .prettierrc                  # Repository-wide formatting rule (printWidth 120)

Commands must be executed inside

website

website/functions

; there is no root-level

package.json

Setup

Use Node 22 (Volta will pin automatically; otherwise install via nvm).

Install front-end dependencies:

cd website
npm install

Install Cloud Functions dependencies:

cd website/functions
npm install

Install the Firebase CLI (
```
npm install -g firebase-tools
```
) and authenticate with
```
firebase login
```
before deploying or running emulators.

Environment and Secrets

Copy

website/functions/.env-template

.env

and fill in

OPENAI_API_KEY

and

SENTRY_DSN

for local or production use.

For local Cloud Function emulation or image uploads, add your Firebase service account key at
```
website/functions/src/service-account-key.json
```
(template provided in the same folder).
Never commit populated
```
.env
```
files or service account keys.

Development Commands

Website (

website/

)

```
npm start
```
- run the CRA development server.
```
npm run build
```
- create a production build (required before deploys).
```
npm test
```
- run Jest tests via CRA (watch mode by default).
```
npm run deploy
```
- deploy Hosting and Functions. Runs
```
npm run build
```
first.

Cloud Functions (

website/functions/

)

```
npm run build
```
- compile TypeScript to
```
build/
```
.
```
npm run serve
```
- build then start the Firebase emulator for Functions.
```
npm run test
```
- execute Jest unit tests.

npm run deploy

- deploy Functions only (

firebase deploy --only functions

Keep strict TypeScript checks passing in both projects (

tsconfig

files enable strict mode).

Firebase Workflow Notes

Hosting and Functions share the Firebase project declared in
```
.firebaserc
```
inside
```
website/
```
.
Update
```
website/storage.rules
```
when altering storage behavior and deploy with
```
firebase deploy --only storage
```
.
Favor the local emulator (
```
npm run serve
```
) during development to avoid hitting production resources.

Validation Checklist

Run these before sharing work:

```
cd website && npm run build
```
```
cd website && npm test
```
```
cd website/functions && npm run build
```
```
cd website/functions && npm test
```
Format touched files with Prettier:
```
npx prettier --write <files>
```

Code Style and Conventions

Keep related statements together and separate distinct steps with blank lines; clarity beats compactness.
Prefer small, composable React components. Co-locate component-specific helpers alongside the component.
Use TypeScript interfaces or types, not
```
any
```
, unless interacting with untyped external data. Document assumptions with short comments when necessary.
Prefix all type-only imports with the
```
type
```
keyword (for example,
```
import type { Foo } from './Foo';
```
).
Stick to named exports. Avoid default exports unless required by third-party APIs.
Use template strings for combining dynamic text; avoid string concatenation with
```
+
```
.
Define React component prop interfaces separately and destructure inside the function body for readability.
Maintain file sizes under roughly 400 lines. Extract utilities or components when they grow large.
Do not commit build artifacts or secrets.

Helpful References

Project overview and deployment steps:
```
README.md
```
Firebase CLI documentation: https://firebase.google.com/docs/cli
Create React App documentation: https://create-react-app.dev/docs/getting-started/

Mirror existing patterns in

website/src

and

website/functions/src

when extending the codebase. When unsure, ask for clarification rather than guessing.

AJTU - Agent Instructions

AJTU - Agent Instructions

Tech Stack and Tooling

Project Layout

Setup

Environment and Secrets

Development Commands

Website (
`website/`
)

Cloud Functions (
`website/functions/`
)

Firebase Workflow Notes

Validation Checklist

Code Style and Conventions

Helpful References

Related Skills

Nano Banana Pro

Markdown Converter

1password

AJTU - Agent Instructions

Tech Stack and Tooling

Project Layout

Setup

Environment and Secrets

Development Commands

Website (
`website/`
)

Cloud Functions (
`website/functions/`
)

Firebase Workflow Notes

Validation Checklist

Code Style and Conventions

Helpful References