This is the brief this page was built from: version 2, as dictated by voice and written up by Claude. Lightly sanitised. The page was later renamed "BdotRads AI Skool" and moved to /ai_skool/. A second, shorter request then added the Pi transcript and the "How this page was built" tab. ---------------------------------------------------------------------- # BdRAIGuide (v2, tabbed) A tabbed, plain-English explainer page showing how AI actually works, how Brad sets it up with agents (including by voice while driving), and how a business can bring AI in safely and get real value from it. Written for a civil engineer / business owner who understands the basics but is not an IT person. Hosted as a BdRapps page at apps.bdotrad.me (suggested path: /aiguide). Supersedes the single-scroll layout in the first version of this brief. Content from that version is reused, now split across tabs. Single static page, no backend. Plain HTML, CSS and JS in public/, diagrams as inline SVG or CSS (no heavy libraries). Deploy with publish.ps1 as per the other BdRapps pages. Australian English, metric. ## Purpose Give a non-IT business owner a clear mental model of how AI works, show a real example of it being used hands-free, and explain the one trick that matters most: have an agent summarise documents into markdown files once, so later agents read the cheap, fast summaries instead of re-reading raw PDFs. The page stands on its own as something Brad can send as a link after a conversation. ## Audience and tone - Smart, practical, time-poor. Civil engineer type: likes diagrams, numbers and concrete examples, dislikes hype and jargon. - Conversational but precise. Short paragraphs. Define terms on first use (model, context, agent, token, prompt). - Honest about limits. Say where a human must check. - No sales pitch, no vendor cheerleading. ## Page structure One page, a tab bar across the top, one tab visible at a time. Tabs: 1. **See it in action** (voice conversation) 2. **How AI works** (neural network diagram and context) 3. **Agents and a PM** 4. **The PDF trick** 5. **Doing it safely** 6. **Getting the best out of it** 7. **Watch and read next** Tab behaviour: - Tab state in the URL hash (for example /aiguide#pdf-trick) so Brad can link straight to one tab. - Keyboard accessible, works on mobile (tab bar scrolls horizontally if needed). - Previous / Next buttons at the bottom of each tab to walk through in order. - A short one-line takeaway at the top of each tab. - Footer and disclaimer sit below all tabs. ## Tab 1: See it in action (voice conversation) Purpose: show, rather than tell, how Brad works with AI, including that it can all be done by voice while driving. - Short intro: Brad talks to Claude by voice in the car. It reads his files, creates briefs, saves them to his Google Drive, and a dev agent on a Raspberry Pi picks them up and builds the pages. No keyboard involved. - Show a **sample conversation** as a chat-style transcript. Brad will supply the real transcript separately (see below). Style it as alternating bubbles, with Brad on one side and Claude on the other, and small annotations in the margin pointing out what is happening ("Claude checks how earlier briefs are laid out", "Claude saves the brief into the project folder", "Brad talks naturally, no special commands"). - Annotated flow strip above the transcript: Brad speaks -> Claude reads existing notes and files -> Claude writes a brief (.md) -> brief lands in a shared Drive folder -> dev agent on the Pi builds and deploys -> page goes live. - Callout: "The brief is just a text file. This page was built from one." Link to a sanitised copy of the brief that built this page. - Optional: a short audio clip or a "play transcript" typing animation. Keep it lightweight; no autoplay. Transcript handling: - Brad will paste or drop the transcript as a file in this project folder (suggested name: transcript.md or transcript.txt). If it is not there when building, create the tab with a clearly marked placeholder and log it in Requests.md. - Before publishing, sanitise: remove anything confidential or personal (names of colleagues or clients, internal project details, email addresses, Drive IDs, folder IDs, file paths that reveal anything private). Keep it generic. - The transcript can be trimmed to the useful part. Keep the flow of: idea -> clarifying question -> Claude checks existing conventions -> brief created. Cut tool-call noise and dead air. ## Tab 2: How AI works Keep it simple. Do not explain how a neural network works internally. Show where it sits and what goes in front of it. Diagram (inline SVG, animate gently on tab open): - **Left**: stack of text files representing what goes in: agent instruction file, reference notes, project history, relevant documents, and the user's question. - **Middle**: these merge into a single **context bundle**, labelled "the part you control". - **Right**: a stylised neural network drawn as layers of nodes and connecting lines (input layer, a few hidden layers, output layer), labelled "the model", with a small cloud icon and a note that it usually runs in the cloud, run by a provider, though local models exist on your own hardware. - **Far right**: the answer comes out as text. - Arrows left to right, with the context bundle visibly going into the input side of the network. Key points under the diagram (short): - The model does not remember you. Each time, it only sees the text you hand it. - So setting AI up for a business is mostly about **what text you put in front of it**, not changing the model. - Plain text files do the heavy lifting: instruction files, notes, history, style guides. - There is a limit to how much text fits in one go, and cost scales with the amount of text processed. Tidy, compact inputs matter. (This sets up the PDF trick.) Optional interactive: hover or tap each block in the diagram to see a one-line explanation. A toggle for "cloud model" vs "local model" that moves the network icon and lists one pro and con each. ## Tab 3: Agents and a PM - An **agent** is the model plus a specific instruction file and a specific job (for example "the document summariser", "the web developer", "the reviewer"). - A **PM agent** takes a request, breaks it into tasks, hands each to a specialist agent, then checks and assembles the results. Humans stay in charge of the goal and final approval. - Why specialists beat one big generalist: each has a short focused instruction file, stays on task, is easier to correct, and uses less context. - Diagram: Brad -> PM agent -> specialist agents -> shared folder of notes and briefs. Click an agent box to see an example instruction file (short, generic). - Generic examples (no confidential detail): a dev agent that builds small web tools from a written brief, a summariser agent that digests manuals and reports, a notes agent that files information into a library. - Show a short example of an agent instruction file as a code block (a made-up "summariser agent" with role, rules, output format). ## Tab 4: The PDF trick (summarise once, read many times) The key nuance of the page. Make it visual. - Wrong way: point every agent at a folder of PDFs. Slow, expensive, re-reads and re-interprets the same documents each time, and can miss things in long or badly formatted PDFs. - Better way: one **summariser agent** reads each PDF once and writes a structured markdown file (title, purpose, key facts, numbers, decisions, open questions, plus the path back to the source PDF and page numbers). - After that, all other agents scan the small markdown files first and only open the original PDF when they need exact detail. The markdown tells them where to look. - Benefits: faster, cheaper, more consistent, searchable, and humans can read the summaries too. Easy to spot-check a summary against its PDF to build trust. - Honest caveat: a summary can drop or distort detail. Keep the PDF as the source of truth, keep page references, and have a human review summaries for anything high-stakes. Interactive element: a before/after toggle. - "Without summaries": 40 PDFs all feeding into every task. - "With summaries": 40 PDFs -> 1 summariser -> 40 small .md files -> many agents, with a dotted line back to the PDFs. - Optional sliders for number of PDFs and number of tasks showing a rough relative amount of text read. Label clearly as illustrative only. Show an example summary markdown file as a code block (made-up civil engineering document, for example a geotechnical report or a set of council DA conditions). ## Tab 5: Doing it safely Practical and short. - **Data**: do not paste customer, financial, personal or commercially sensitive information into free consumer tools. Use a business or enterprise plan where the provider commits not to train on your data, and check where data is stored. - **One-page AI policy**: what staff may use, what must never go in, who approves new tools. Include a short copyable template. - **Human in the loop**: AI drafts, a person checks, especially for legal, safety, structural or financial consequences. For engineering calculations and certifications, a qualified person verifies and signs. - **Accuracy**: models sound confident and can be wrong. Ask for sources and working, spot-check. - **Access**: minimum access needed. Read-only where possible. Keep backups. Be careful with anything that can send emails, delete files or spend money. - **Records**: keep briefs, instruction files and outputs so you can see what was asked and produced. - **Start small and low risk**: internal summaries and drafts before anything customer-facing. ## Tab 6: Getting the best out of it - Write clear briefs: purpose, audience, constraints, what done looks like, an example. - Give it good source material. Clean text beats scanned images. - Build a small library of reusable instruction files and notes. This is where the compounding value is. - Iterate: first draft, critique, second draft. - Separate jobs between agents instead of one giant prompt. - Ask it to ask you questions first when the task is vague. - Correct it, then save the correction into the instruction file so it sticks. - Voice is a real option: dictating briefs while driving or walking turns dead time into progress. Link back to Tab 1. Finish with a short **"Where to start on Monday"** box: 1. Pick one repetitive, document-heavy job (summarising incoming reports, drafting meeting minutes, tidying specs). 2. Write a one-page policy. 3. Run one summariser pass over a small folder of non-sensitive PDFs and review the output. 4. Add a second agent that uses those summaries. 5. Review after two weeks: time saved, errors found, next step. ## Tab 7: Watch and read next Curated YouTube list grouped by topic. Each entry: title, channel, length, one line on why it is worth watching. Link out with plain links or lightweight click-to-load thumbnails. Do not embed heavy players on load. Topics: - How large language models work, for beginners (one clear 15 to 30 minute explainer, for example from 3Blue1Brown or Andrej Karpathy's intro talk). - Prompting and giving context well. - AI agents explained, and multi-agent workflows. - AI safety and data privacy for small business. Build note: search YouTube for current, well-regarded videos rather than relying on memory. Verify every link works and the video is real. Prefer recent (last 12 months) where the topic moves fast and note the date. If unsure a link is valid, leave it out and log it in Requests.md. Also include 3 to 5 plain links to provider documentation on data privacy and business plans. Verify these too. ## Design - Clean, calm, lots of whitespace. Diagrams first, text second. - Mobile friendly (likely opened from a text message on a phone). - Dark and light mode friendly, simple colour scheme. - Print-friendly stylesheet so each tab, or the whole page, can be saved as PDF. - No tracking, no cookies, no external scripts beyond what is needed. - Tabs work without a framework: plain JS toggling hidden sections, hash routing. ## Page footer / disclaimer General information only. Not legal, IT security or professional engineering advice. Check your own obligations (privacy, client confidentiality, professional indemnity) before putting business data into any AI tool. Written by Brad based on his own experience; tools and pricing change quickly. ## Notes for the build - Keep explanation text short and punchy. Whole page should read in about 10 to 15 minutes. - Inline SVG for all diagrams so they scale and respect dark mode. - Do not include real client, project, colleague or company information from Brad's work. Examples must be generic or invented. - Page title and subtitle should be something a non-IT person would click on, for example "How to actually use AI in your business (without getting burned)". - Suggested layout: public/aiguide/index.html with css and js alongside, or a single file, whichever matches the other BdRapps pages. Add a link from the apps.bdotrad.me index. - Deploy with publish.ps1, then confirm the page loads at apps.bdotrad.me/aiguide on desktop and mobile, and that each tab hash link works. - Tab 1 depends on the transcript file. Build the rest first and slot the transcript in when it arrives. - Log any questions in Requests.md.