Participant guide

Before the workshop (15 minutes)

Do these at least two days before the first day, so there is time to fix problems.

1. Create a GitHub account. Go to github.com and choose Sign up. Use an email address you check regularly. A personal address is fine.
2. Turn on two-factor sign-in. GitHub will ask you to set this up. Follow its steps with an authenticator app or a passkey. It protects your work.
3. Send the organizer three things:
   • your GitHub username
   • the email address you want to use for your AI helper
   • the web name you'd like: 3 to 30 lowercase letters and digits, such as tulip
   Your web name appears in your app's link in place of your username, so pick something you're happy to share.
4. Accept two invitations. You will get two emails:
   • one from GitHub, inviting you to the workshop's organization, swissnex-lab. Click Join.
   • one from Anthropic, inviting you to the Claude Console. This is the account your AI helper uses. Accept it and choose a way to sign in.
5. Test your laptop. On the laptop you'll bring, sign in at github.com, then open this guide again. If either is blocked, tell the organizer now.

You don't need to buy anything. The workshop pays for the AI helper and for putting your app online.

Step 1: Create your project and open your workspace

Your project is a "repository" (repo) on GitHub: a folder that holds your app's files and remembers every change. You create it from the workshop's starter template.

Create the project (once)

1. Go to github.com and sign in.
2. Open the template at github.com/swissnex-lab/sf2026-template. Click the green Use this template button, then Create a new repository.
3. Fill in the form:
   • Owner: choose swissnex-lab, the workshop organization, not your own name.
   • Repository name: a short name for your app using letters, numbers and hyphens, like guided-tour or feedback-wall. It becomes part of your app's web address.
   • Private.
4. Click Create repository. Within a few minutes your app is already online. Open the Actions tab and click the run at the top. When it shows a green tick, your link is at the bottom of the page. It looks like https://guided-tour.your-web-name.swissnexlab.com.

Other people in the workshop can see your project, but only you can change it.

Open your workspace

Your workspace is a complete coding setup that runs in your browser. GitHub calls it a Codespace.

1. In your repo, click the green Code button, choose the Codespaces tab, then Create codespace on main.
2. Wait two to four minutes the first time. You'll see a progress screen while it prepares.
3. When it's ready you'll see an editor with four areas:
   • Left: a list of your project's files.
   • Middle: whatever file is open.
   • Bottom: a Terminal panel. You can mostly ignore it.
   • Side bar: the icon for your AI helper (Step 2).

Next time, you don't create a new one. Go to github.com/codespaces and click your existing codespace to reopen it. Your work is saved there.

Codespaces pause after 30 minutes without activity. Reopening one takes about a minute and nothing is lost.

Step 2: Meet your AI helper

Your AI helper reads your project, writes and edits code, and runs commands for you. You talk to it in a chat panel inside the editor.

Sign in (the first time)

1. Click the AI helper's icon in the side bar.
2. Click Sign in.
3. Choose Anthropic Console account, then Sign in with your Console account.
4. A browser tab opens. Sign in with the email address you gave the organizer.
5. If the page shows a code, copy it and paste it where your AI helper asks for it.

There is no key to copy or keep safe. If your AI helper asks you to sign in again later, do the same.

Say hello

1. Type this and press Enter:

   Hi! Explain what this project does in plain language, as if I've never coded.

2. Your AI helper reads the files and explains. Ask follow-up questions freely.

How your AI helper asks permission: before it changes a file or runs a command, it shows you what it wants to do and asks you to approve. Read the one-line summary. If it makes sense, approve it. If you're unsure, ask "What will this do?" first.

Your AI helper has a monthly limit set by the workshop. Normal use won't reach it. If it says a limit has been reached, tell the organizer.

Step 3: Preview your app

A preview is a private copy of your app that only you can see. Use it to try changes before anyone else sees them.

1. Ask your AI helper:

   Start the preview so I can see my app.

2. Approve the command it wants to run. It will be npm run dev.
3. A pop-up appears at the bottom right saying your application is available. Click Open in Browser. If you miss it, open the Ports tab next to Terminal and click the globe icon beside the port number.
4. A new browser tab shows your app: a blank page with a heading and one line of text.

Leave the preview running while you work. When your AI helper changes a file, refresh the preview tab to see the result.

The preview link only works for you, and only while your codespace is open. To share your app with others, use Step 5.

Step 4: Make your first change

Start small to learn the rhythm: ask, approve, check the preview.

1. Ask your AI helper:

   Change the heading to "Welcome to [your organization's name]" and use our colours: [describe them, for example dark green and cream].

2. Approve the file changes your AI helper proposes.
3. Refresh your preview tab. You should see the new heading and colours.
4. Not what you wanted? Say so plainly: "Make the green lighter" or "Undo that last change."

That loop is the whole method. Every feature you add, however big, is a series of these small requests.

Step 5: Publish and share

Publishing saves your changes to GitHub. GitHub then checks them and sends the new version to the workshop server, usually within one to three minutes.

1. When you're happy with the preview, ask your AI helper:

   Publish my changes with a short description of what I changed.

2. Approve the save ("commit") and upload ("push") steps.
3. Wait a couple of minutes, then open your public link: https://YOUR-REPO-NAME.YOUR-WEB-NAME.swissnexlab.com, all in lowercase. The exact link is shown at the end of each run in your repo's Actions tab.
4. Share that link with anyone. They don't need an account.

If the new version has a mistake, the previous version stays online. Your public link never shows a broken half-update.

To check whether an update worked, ask your AI helper: "Did my last publish succeed?" Or open your repo's Actions tab. A green tick means it's live. A red cross means something failed, and clicking it shows the reason.

Publish at least at the end of each day. It's also your backup.

Step 6: Store data

If your app needs to remember things, such as visitor feedback, sign-ups or a list of objects, it uses a database. Yours is already set up: a SQLite database that lives with your app.

1. Describe what you want to keep, in everyday terms:

   I want visitors to leave a comment and a star rating (1 to 5) about an exhibition. Store them in the database and show the latest 20 on a page only staff can see.

2. Your AI helper creates a "migration", a small file describing your table. Approve it.
3. Try it in the preview.
4. When it works, ask your AI helper to publish. The database change is applied on the server automatically.

Your preview has its own practice database, and your public app has the real one. Test data in the preview won't appear on your public link. That's intentional.

Photos, audio and documents don't belong in the database. Ask your AI helper to put small files in the app's public folder. Keep each file under about 10 MB. For anything bigger, ask the organizer.

Never store people's personal details (names, emails, phone numbers) unless your organization has approved it. Ask your AI helper to keep things anonymous by default.

Step 7: Connect web services

Your app starts with no features. Your project comes with ready-made examples that stay switched off until you ask for them, including weather, a Telegram bot and text messages. Ask your AI helper: "Which examples does my project have, and how do I turn one on?"

Keys are secrets

Many services give you a key or token, a long password that lets your app use them. Anyone who has it can use your account.

• Never paste a key into the AI chat, into a file, or into an email.
• Keys go in two places only, described below. If your AI helper ever suggests putting a key in a file, say no.
• If a key is shared by accident, tell the organizer straight away so it can be replaced.

Adding a key

Keys are stored in your GitHub repo's settings, in two places: one for your public app and one for your preview. Use the same name in both.

1. In your repo on github.com, open Settings, then Secrets and variables in the left menu.
2. For your public app: choose Actions, click New repository secret, enter the name (for example TELEGRAM_BOT_TOKEN) and paste the value. Save.
3. For your preview: choose Codespaces, click New repository secret, and add the same name and value. If your Codespace is open, it offers to reload. Accept.
4. Tell your AI helper the name you used, never the value: "I've added TELEGRAM_BOT_TOKEN. Use it for the bot." Then publish.

The names your app uses are listed in the file secrets.example.env. It starts empty, and your AI helper adds a name each time a feature needs a secret.

Service notes

Telegram and Twilio send messages to your public link, not your preview. Publish first, then test them there.

Step 8: Build your demo

What to build: five parts

The workshop asks you to build a small demo that brings together five parts:

1. A data source: information your app collects from somewhere else, such as a museum's collection or the weather.
2. An interaction: something a person does, and the app answers.
3. A browser sensor: something the phone can sense, such as where it is or how it is tilted.
4. An integration: a connection to a service people already use, such as Telegram or a map.
5. A PWA: an app people can install on their phone.

The README.md file in your project has ideas, links and ready-made examples for each part. Open it from the list of files on the left.

Make it work for everyone

Your demo has to work for people who can't see the screen, can't hear, can't use a mouse or a touch screen, or can't tilt a phone. The standard for this is WCAG 2.1, level AA.

Your AI helper follows the standard as it builds. If you ask for something that breaks it, your AI helper tells you what the problem is and offers a version that passes. The decision is yours. The README.md file lists what only you can do, and five checks to make before you publish.

Plan first, then build in small steps

1. Open a planning conversation:

   I work at [organization]. My idea is [one or two sentences]. The people using it will be [visitors / staff / schools]. Before writing any code, suggest a simple first version I could finish in two days that covers the five parts in README.md, broken into small steps.

2. Ask your AI helper to do the first step only. Preview it, fix it, publish it.
3. Repeat for each step. Publish after each working step.

Requests that work well:

• Be specific about the result: "Add a button under the map labelled 'Tell me more'" beats "make it better."
• Describe problems as you see them: "When I click Submit nothing happens and the page stays the same."
• Ask for explanations: "Explain what you just changed in two sentences."
• Ask for options: "Give me three ways to show the opening hours, and which is easiest."
• Keep conversations focused: start a new chat for each new feature. Long chats get muddled.

If your AI helper gets stuck going in circles, stop. Ask "Undo your changes since my last publish," then describe the goal again more simply.

Troubleshooting

Most problems are fixed by describing them to your AI helper. Try that first, then use this table.

After the workshop

You keep full access for the funded period. Everything you did during the workshop works the same way at home or in the office.

• Reopen your codespace at github.com/codespaces and carry on.
• Aim for a short session every week or two. Small, regular changes go further than one big push.
• Share your link with colleagues and gather feedback. Paste their comments straight into the chat: "A colleague said: [feedback]. How could we address it?"
• For help, reply to the organizer's welcome email.

When the funding period ends

The organizer will email you 30 days and 7 days before the end date. When funding ends:

Before the end date, decide with your organization whether to take the project over. The organizer can move your repo to your organization's own GitHub account and give you a copy of your database. Your app is an ordinary Node.js web app with a SQLite database, so any web developer, or anyone with an AI coding tool, can run it on another server and continue where you left off.

Glossary