Use this file to guide you through the Glimpse setup process. There isn't much to do but if it's your first time, some concepts may be new, so please follow them carefully and reach out if you have any questions.

The instructions in this file are for you. It's important to distinguish the instructions in this file from the instructions in the other files in this folder, which are for Townie.

The prompts that you will enter into Townie are in blockquotes, like this:

I'm a prompt for Townie

You copy and paste these prompts into Townie and run them, and Townie will build Glimpse from the ground up: it will scaffold Glimpse, add then add features like user authentication, webhook authentication, caching, a React front end, and a way to collect metrics.

Once those bits are complete, Glimpse will be feature complete and you can add and experiment with new features til your heart's content.

To use this runbook, you'll need to have these things ready:

1. A val.town account
2. A Remix of this Val in your val.town account
3. The environment variables imported into your Remix

Once your environment variables are saved to this Val (i.e., once you've imported vars.env to your Remix), all of the environment variables are available to the Val and Townie, and val.town and Notion are connected to each other. (Note that environment variables are secret and secure on val.town.)

If you don't have the environment variables, contact your administrator.

This is a look at what the environment variables are, and what they do. (They are not the environment variables themselves; you'll need to get those from your administrator.)

The most important thing to understand about them is that they are required to connect val.town to Notion, and to connect this Val's code to the Notion databases that hold the demo content.

• NOTION_API_KEY - Your Notion integration API key
• NOTION_WEBHOOK_SECRET - Matches the X-API-KEY custom header coming from Notion webhooks to /tasks/* endpoint(s)
• GLANCE_DEMOS_DB_ID - Your Notion database ID for demos, which are personalized to prospects and have unique URLs
• GLANCE_CONTENT_DB_ID - Your Notion database ID for demo page content, which are compiled into demos
• GLANCE_INTERACTIONS_DB_ID - Your Notion database ID for pageview metrics and the like

Now that you're through setup, you can instruct Townie to build this Val by pasting prompts into Townie.

In Townie, select this Val, and prompt Townie with this line:

Scaffold this Val with what you see in /_townie/01-scaffold.md

When Townie completes the scaffolding task, it will tell you what you need to do next. Have fun!

Add auth to this Val with what you see in /_townie/02-auth.md

Add webhook auth to this Val with what you see in /_townie/03-webhooks.md

Add an endpoint at /views/glimpse/:id by following the instructions in /_townie/04-view.md

Add a route for /glimpse/:id by following the instructions in /_townie/05-glimpse.md

Follow the instructions in /_townie/07-save.md to add the /tasks/url endpoint

Add related pages to the /glimpse/:id endpoint by following the instructions in /_townie/08-related.md

TODO: have Townie's success message at the end tell the user to update Notion automation with the URL on the main branch

1. In Notion, click the URL in the URL property; it should not work. That URL is from a previous branch that we deleted.
2. Go to main.tsx and get the URL for this branch
3. Edit the automation on the "Set URL" button with that URL; make sure it incudes the /tasks/url endpoint
4. Save the button automation
5. Click the button in Notion
6. You should see the URL property update with a URL to a Glimpse endpoint on val.town
7. Click the new URL
8. Authenticate
9. CTRL+F glimpseContent -- that's the object that holds the related content you see in Notion

1. Merge related into main
2. Delete the related branch
3. Create a new branch called cache

Use the instructions in /_townie/09-cache.md to implement a cache for Glimpse demos at the `/glimpse/:id` endpoint

1. merge cache into main
2. set cron interval to 1 minute

After merging into main:

CRITICAL: Go to the Val Town web UI and set the cron schedule for /backend/crons/cache_glimpse_data.ts to run every minute

Now that we have a responsive endpoint, we can iterate quickly on the front end without waiting for notion to respond and the JSON to render.

1. Delete the cache branch
2. Create a new branch called react

Use the instructions in `/_townie/10-react.md` to implement a React bootstrap for the `/glimpse/:id` endpoint

1. test /glimpse/:id endpoint in the react branch
2. if it looks good, merge react into main
3. delete react branch

1. Create a new branch called html
2. Go to townie and select the html branch
3. Enter this into townie:

TODO: make sure that the html instructions are clear about persisting the page layout with header including auth, sidenav, main content and footer.

TODO: UPDATE THE ENDPOINT BIT BELOW WITH A REAL URL BUILT BY TOWNIE LIKE IN THE LINK STEP ABOVE

use the instructions in `/_townie/11-html.md` to format the Notion data as HTML. Use this endpoint for testing: `/glimpse/20089f51-c349-803b-a940-edd14b011876

1. test /glimpse/:id endpoint in the html branch
2. if it looks good, merge html into main
3. delete html branch

1. Create a new branch called pdf-embeds
2. Go to Townie and select the pdf-embeds branch
3. Enter this into Townie:

follow the instructions in `/_townie/12-embed.md` to implement rendering for certain embed blocks

The link is rendered as a button but it 404s. We need to implement the /glimpse/:id/pdf route.

1. Create a new branch called pdf-route
2. Go to Townie and select the pdf-route branch
3. Enter this into Townie:

follow the instructions in /_townie/PDF-ROUTE.md to implement rendering for certain embed blocks

1. vt on your computer. If not, follow the instructions on the Github README
2. Use vt to clone the Val to your computer

1. Go to main.tsx, click the green HTTP button, and copy the URL of this Val.
2. In Notion, add a button to the Glimpse Demos database
3. Edit the automation on that button: add the URL fromj step 1 and then append /tasks/notion-webhook to it
4. Click the 'custom header' link under the webhook URL field and add this key and value: Key: X-API-KEY, Value: <x-api-key value>. (Find the value in the NOTION_WEBHOOK_SECRET key in vars.env)
5. Click the save button
6. Click the automation button in the Notion database row
7. Go to the Logs in your Val and see the latest log statement, which should outline success or failure of your webhook and webhook auth

Next, tell the user that they can merge this branch into main, then delete this branch, and then they can proceed to the next step: glimpse. Don't write any code.

In the steps that follow, you will see instructions for you to paste and run in Townie (in code blocks) and a few instructions for you, mostly numbered steps related to creating and deleting "branches."

Branches are important in development, even AI-enabled development. (Maybe more so.) With branches, we protect the code that's already running and working in our app while we develop new features. Once the code in a feature branch meets our needs, we can merge it into the main branch. Learn more about branching on val.town

1. Do not leave vars.env on your desktop
2. Move vars.env to the root of this project
3. Note that vars.env is already in the .vtignore file, which means that it will not be uploaded to val.town when you push new features or updates with vt

1. In Notion, add a button to a database row in the Glimpse Demos database called "Staging: set URL"
2. Edit the automation on that button to be a webhook that hits https://<branch subdomain url>/tasks/url
3. Add the custom header for webhook auth: Key: X-API-KEY and Value: <custom header value>. (Find the value in the NOTION_WEBHOOK_SECRET key in vars.env)
4. Save the button automation
5. Click the button in Notion
6. You should see the URL property update with a URL to a Glimpse endpoint on val.town
7. If it fails, clues as to why are in the logs
8. Go to the Logs in your Val and see the latest log statement
9. If there's an error captured there, explain that to Townie