Add UX report.

Author: ntoll

docs/ux/ai_default.md

@@ -0,0 +1,98 @@
+# Theme E: AI is now the default route in, through and around PyScript
+
+## What it is
+
+Large language models as the medium of discovery, learning,
+construction and documentation for PyScript. This is not a single feature
+request; it is a shift in the environment, community and industry in which we
+operate.
+
+## What it means for PyScript
+
+AI now sits on almost every path a user takes.
+Discovery: Nitau, an engineer, found PyScript because "the LLM told me that
+PyScript runs Python in the browser using WebAssembly." Building: Claudiu, a
+hobbyist, has moved from writing code to directing it, teaching Claude to use
+his PyScript helper functions and stepping back until "I'm never reading the
+code, because the code is being produced much faster than I can read it."
+Momin, an engineer, has built an entire platform around a copy-paste-from-LLM
+workflow for non-technical students. Sai, an informatician, runs an AI agent
+that generates Python executed in PyScript, and finds it competitive with a
+"billion-dollar company's" full coding-agent setup, partly because "PyScript on
+the browser is way faster, I can see what's happening."
+
+There is a clear and important spread of attitudes, which we should represent
+faithfully rather than lose under the generic "AI" term. At one end, Claudiu is
+comfortable not reading the code. In the middle, Nitau uses "basic prompting"
+as "a conscious choice," remaining "the gatekeeper" who reviews everything
+before it enters his codebase, and Łukasz treats it as "a productivity
+booster, but sometimes it's more like a slot machine." At the other end,
+Kattni does not use AI at all, on ethical grounds (training data, climate, and
+what she called an "evangelical" culture), and also because her self-assessed
+Python knowledge means she "wouldn't be able to tell whether what I was just
+given is good or bad." Anna, a learner, deliberately avoids AI for schoolwork
+on principle while using it for lab work to move faster.
+
+Two practical sub-findings deserve emphasis. First, model quality against
+PyScript changed materially and recently: Łukasz reported that before December
+2025, using AI with PyScript was "pretty dangerous," and that with Opus 4.5 it
+became "tractable," speculating it may have been trained on the PyScript docs.
+Momin noted LLMs "cannot detect the current version of PyScript" and sometimes
+add random imports that break the code. Second, and strategically most
+important: our documentation increasingly reaches humans only after passing
+through an LLM. Nitau observed that he fed the docs' Markdown files to an AI
+and "it did a perfect job." Nicholas's own reflection, echoed to several
+interviewees, is that the people who read our documentation "are not people,
+they're LLMs."
+
+This extends beyond documentation. As AI-native tooling (coding agents such as
+Claude Code and GitHub Copilot) becomes the default way practitioners build,
+the question is no longer only whether a human can read our docs, but whether
+an AI agent can correctly represent our APIs and services when a practitioner
+prompts it. How well we express our work to these tools increasingly
+determines the quality of response a practitioner receives about PyScript, and
+about Anaconda's products more widely. Nicholas has
+[written in depth about the challenges this poses](https://ntoll.org/article/predico/).
+
+## Future steps
+
+Treat "how our resources are consumed by LLMs" as a
+first-class engineering, education and documentation problem (work Nicholas
+has already begun). Ensure the docs, API surface and examples are structured
+so an LLM produces correct, version-aware PyScript; the version-detection
+failure Momin reported is a concrete target. Keep a genuinely AI-free path
+fully supported and first-class, both because some valued community members
+(Kattni) require it and because learners (Anna) deliberately choose it. Avoid
+taking a single position on AI; the community spans the full range and trust
+depends on us respecting and embracing that. Treat how our APIs and services
+are represented inside AI-native coding tools as an extension of the
+documentation problem: what a coding agent generates about PyScript is now
+part of our public interface.
+
+## Standing across archetypes
+
+Universal, but polarised. Engineers and
+hobbyists are furthest into AI-assisted building; educators are the most
+cautious; learners are thoughtfully selective.
+
+## Challenges
+
+A definitional confusion has dogged discussion of AI and
+PyScript inside Anaconda. "AI in the browser" can mean two quite different
+things.
+
+1. The first is running LLMs *inside* the browser runtime itself, using
+   experimental web APIs. 
+2. The second is what every AI-using practitioner in these interviews actually
+   does: use LLMs as ordinary and complementary tools (cloud services or
+   agents) that generate or assist with Python, which then runs in PyScript.
+
+Internal advocacy at Anaconda has focused on the first sense of "AI in the
+browser" (running models inside the browser); all the practitioner evidence in
+this report concerns the second (LLMs as external tools generating PyScript
+code or consuming PyScript-based resources). Acting on this theme therefore
+requires realigning internal direction with the evidence, rather than
+advocating for something with no demonstrated use case, market signal or
+community demand. That realignment is beyond the PyScript team's sole
+authority. Furthermore, were in-browser models ever wanted, JavaScript would be
+the better-performing tool for the job.

docs/ux/appendix1.md

@@ -0,0 +1,68 @@
+# Appendix 1 - Core Concepts
+
+PyScript's approach rests on three interconnected core concepts that
+help us move from the abstract to the concrete (and back again):
+
+## Archetypes
+
+Archetypes are abstract definitions of roles or postures a practitioner may
+adopt. We currently use six archetypes: 
+
+* Learner - whose primary focus is skill and knowledge acquisition.
+* Educator - helps, mentors and creates resources for the learner archetype. 
+* Engineer - builds valuable things with technology, often in a professional
+  capacity.
+* Informatician - where technology is an important aspect of their job,
+  while their role is in an orthogonal discipline to coding (for example,
+  they're a data scientist, meteorologist, developer relations advocate or
+  medical informatics analyst).
+* Administrator - an information worker who uses tech as a secondary
+  (facilitating) aspect of their job, which focuses on managerial,
+  bureaucratic or vocational functions. For example, the COO trying to build
+  a status dashboard or a doctor refining the EHR (electronic health record)
+  processes in their hospital.
+* Hobbyist - is enthusiastic about tech (for tech's sake). They might think
+  of themselves as a "maker", "geek" or participate in open-source community
+  activities. 
+
+These archetypes help us to think structurally about the different ways people
+might approach and use PyScript, without assuming any single practitioner
+fits neatly into one category. In reality, we embody multiple archetypes
+depending on context or need.
+
+## Personas
+
+Personas are fictional yet carefully constructed embodiments of archetypes.
+Each persona has a name, cultural context, background and specific needs.
+They exist to help us explore concrete examples of requirements, working
+patterns, and contextual motivations. Personas bridge the gap between abstract
+thinking about practitioner types and the messy, specific reality of actual
+human needs. They help us engage with enlarged empathy and imagination, rather
+than through small-minded stereotypes that constrain our thinking. They are
+the foil to feature-focused technical work based on "cool" technology and
+coding fashions.
+
+Examples of such personas can be
+[found in the Invent framework](https://invent-framework.github.io/design/#personas),
+(work from 2023).
+
+## Practitioners
+
+Practitioners are real people who may encompass one or more persona
+characteristics (like the participants in these interviews). They are the
+ultimate source of truth. We validate our assumptions, refine our thinking,
+and revise how we define both archetypes and personas based on what
+practitioners demonstrate and tell us. Because of PyScript's open-source
+foundations, engagement with certain sorts of practitioner happens regularly
+through informal community channels. This research aims to formalise, broaden
+and deepen that engagement.
+
+This vocabulary originates from work undertaken in 2023 for the Invent
+framework (built upon PyScript) and draws upon Nicholas's experience with UX
+research at organisations including The Guardian (which had their own
+in-house UX "lab") and Marks and Spencer (who make extensive
+use of joined-up personas in many teams, from tech and product to marketing
+and PR). It reflects the PyScript OSS team's belief in holistic collaboration:
+software engineers must work and collaborate with UX and product colleagues,
+and not merely implement "features" in isolation or based on guesswork and
+tech fashions.

docs/ux/appendix2.md

@@ -0,0 +1,31 @@
+# Appendix 2 - Theory and Practice
+
+This research was also informed by an internal Anaconda UX framework
+organised around segments, personas and scenarios. Because this report will
+be read outside Anaconda, we describe how that framework relates to
+PyScript's approach without reproducing its confidential detail. Its segments
+describe practitioner types as functional roles within organisational
+structures, and map closely to PyScript's archetypes ([appendix 1](./appendix1.md)), which
+describe postures towards creating with code. Its personas work just as
+PyScript's do, giving the two frameworks a shared vocabulary. Its most
+valuable addition is scenarios: three descriptions of what practitioners try
+to accomplish regardless of role or background - Setting Up (their
+environment, tooling and initial access to assets), Building and Development
+(creating, testing and iterating on technical work) and Sharing and
+Collaboration (distributing outcomes, working with others, managing access).
+Every practitioner in this report navigates a variation of all three, and
+they are a welcome lens on a practitioner's journey that PyScript's research
+will adopt.
+
+Related is the notion of "AI-native" development, a term
+[coined by Gartner](https://www.gartner.com/en/articles/top-technology-trends-2026)
+to describe systems, products and engineering practices that integrate AI as
+a core, foundational component rather than a bolted-on feature. Gartner's
+specific forecasts are informed speculation and we treat them as such, but
+the term is the current language of our commercial users, and this report
+engages with what it names: how practitioners now build with AI-native
+tooling, and how well our APIs, services and documentation are represented
+inside those tools. [Theme E](./ai_default.md) presents the practitioner evidence for this and
+[next step #4](./conclusion.md#4-make-pyscript-an-excellent-citizen-of-the-llm-ecosystem) proposes the response. It is where the open-source practitioner
+focus of this report and Anaconda's commercial interests most clearly
+converge.

docs/ux/case_study.md

@@ -0,0 +1,67 @@
+# Case study: the Tufts tooling arc (PyScript.com reliability and TuftsHub)
+
+This case study sits slightly apart from the six themes because it is a single,
+continuous story told across two calls, and because its subject, Chris and
+Ethan at Tufts, is an institutional relationship rather than an individual
+archetype. It is included in full because it does three things at once: it
+states the PyScript.com reliability problem first-hand, it enumerates exactly
+what a replacement must provide, and it demonstrates the engagement loop this
+report advocates.
+
+## The problem
+
+Chris and Ethan both praised PyScript.com's ease of
+developing, sharing and cloning, and the instant browser-based start it gives
+students. The failure is reliability. In Chris's words the service "does with
+fair regularity" become "ungodly slow", and when it does so mid-lesson "the
+class kind of falls apart", with a middle-school workshop, college classes and
+company presentations all named as failures. Because PyScript.com is
+unmaintained, the fix path runs through colleagues and infrastructure and
+takes fifteen minutes to half an hour, which is no use in front of a class.
+This is the first-hand version of the crashes Anna and Hammad reported
+second-hand.
+
+## What a replacement must provide
+
+The professors were willing to move
+hosting to GitHub Pages, which they value for teaching industry-standard Git
+workflows, but only three PyScript.com capabilities stand in the way: channels
+(sharing information between pages over WebSockets), an API proxy (so a secret
+key is never exposed), and authorisation (so a project is restricted to
+approved people, since an open project is, as Ethan noted, "attached to my
+credit card"). A useful clarification emerged on channels: they already run on
+the same publish/subscribe logic as the industry-standard MQTT message bus,
+with PyScript.com acting as the broker, and Chris confirmed they have
+connected Raspberry Pis and ESP32s to the PyScript WebSocket. The desired
+solution was a one-click, pip-installable tool that "just sits there happily
+humming away in the corner like a fridge", local-first and offline-capable
+(Ethan's "aeroplane version"), syncing to a GitHub folder, and self-hostable
+on Tufts, Amazon or any other infrastructure. Nicholas noted this effectively
+amounts to a white-label "PyScript.com enterprise" instance, a useful data
+point and potential opportunity for Anaconda.
+
+## The response and its review
+
+Nicholas built TuftsHub (thub) against these
+requirements, and the second call reviewed it. Chris demonstrated it serving an
+app locally straight from the source he was editing, with user management built
+in. Feedback and new requests followed: a one-action pull of an existing
+PyScript.com project (reading the `pyscript.toml` and assembling a complete
+offline copy), support for running several projects at once, and a
+single-window view combining files, code and live preview to escape the sprawl
+of many editor and browser windows. Nicholas was careful throughout not to
+reinvent PyScript.com's in-browser IDE, preferring to open the design question
+to colleagues Martin and Josh and the wider community, and floated his earlier
+PySnippets work as a possible starting point.
+
+## Why it matters
+
+Beyond the concrete requirements, the arc is the report's
+clearest example of engagement done effectively: requirements gathered on the
+record so the movement from problem to solution is visible, a proof of concept
+built quickly, a review to refine it, and then a deliberate opening-up, keeping
+the repository under the Tufts GitHub organisation, seeking a better name than
+thub, releasing on PyPI, and shifting future requests from private Slack to
+public GitHub issues. It is both a source of requirements (Themes
+[A](./friction_free.md), [B](./js_boundary.md), [D](./onboarding_path.md)) and
+a template for how this kind of work should run ([Theme F](./visibility.md)).