If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/railsbridge/docs shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 28+ active contributors
• Distributed ownership (top contributor 22% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live railsbridge/docs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/railsbridge/docs.

What it runs against: a local clone of railsbridge/docs — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in railsbridge/docs | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 813 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of railsbridge/docs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/railsbridge/docs.git
#   cd docs
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of railsbridge/docs and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "railsbridge/docs(\\.git)?\\b" \\
  && ok "origin remote is railsbridge/docs" \\
  || miss "origin remote is not railsbridge/docs (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "app.rb" \\
  && ok "app.rb" \\
  || miss "missing critical file: app.rb"
test -f "lib/site.rb" \\
  && ok "lib/site.rb" \\
  || miss "missing critical file: lib/site.rb"
test -f "lib/markdown_page.rb" \\
  && ok "lib/markdown_page.rb" \\
  || miss "missing critical file: lib/markdown_page.rb"
test -f "lib/step.rb" \\
  && ok "lib/step.rb" \\
  || miss "missing critical file: lib/step.rb"
test -f "lib/contents.rb" \\
  && ok "lib/contents.rb" \\
  || miss "missing critical file: lib/contents.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 813 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~783d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/railsbridge/docs"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A Sinatra-based curriculum delivery platform that serves educational workshop content (installfest instructions, intro-to-rails tutorials, JavaScript snake game) from markdown, step files, and MediaWiki sources. It compiles structured course materials into an interactive web experience with progress tracking, step-by-step navigation, and multi-locale support (English, Spanish, etc.). Monolithic Sinatra app with content-first architecture: course materials live in sites/{locale}/{course_name}/ as markdown/step files; lib/ contains page renderers (MarkdownPage, StepPage, MediaWikiPage, etc.) and a Site class that orchestrates content loading and routing. app.rb wires the Sinatra endpoints. Assets (JS/CSS) are in assets/stylesheets and assets/javascripts, with specific features like checkboxes.js and step.scss handling student progress.

RailsBridge volunteers and workshop facilitators who need to deliver consistent, localized programming curriculum to absolute beginners; junior developers learning Ruby/Rails who use the public docs.railsbridge.org site; and educators building on top of the curriculum framework.

Production-ready and actively maintained. Deployed to docs.railsbridge.org with CI via GitHub Actions (.github/workflows/rspec.yml), has a Gemfile with locked dependencies, multiple language support, and a clear CONTRIBUTING.md. The age and commit recency are not visible in the provided data, but the structured test setup and professional configuration suggest a mature, ongoing project.

Low risk on the code side (Sinatra is lightweight and stable), but risk around content maintenance: no visible issue tracker status in the data, and courseware quality depends on community contributions which may have irregular schedules. Single locale file structure (locales/en/) means adding a new language requires discipline. No bundled package manager lock file visible beyond Gemfile.lock.

Cannot determine from provided metadata (no commit history, PR list, or issue tracker data visible). The presence of .github/workflows/rspec.yml suggests active testing practice, but the state of development is unknown.

git clone https://github.com/railsbridge/docs.git && cd docs && bundle install && bundle exec rake run. Open http://localhost:9292 in your browser.

Daily commands: bundle install && bundle exec rake run (uses rerun for auto-reload). Fallback: rackup. Server listens on 0.0.0.0:9292. To serve a different locale: SITE_LOCALE=es bundle exec rake run.

• app.rb — Main Sinatra application entry point that routes all requests and initializes the site framework.
• lib/site.rb — Core abstraction for handling site structure, content loading, and navigation logic across all curriculum projects.
• lib/markdown_page.rb — Primary content renderer converting Markdown files into HTML pages; used for majority of curriculum content.
• lib/step.rb — Models individual curriculum steps with parsing logic for .step files, the primary content format for workshops.
• lib/contents.rb — Manages in-memory content indexing and lookup across all sites and locales to enable fast page resolution.
• sites/docs/docs.step — Sample step file demonstrating the .step format convention used throughout all curriculum content.
• Gemfile — Declares Sinatra, Erector, and asset pipeline dependencies critical to understanding deployment and runtime stack.

Add a new curriculum step to an existing site

1. Create a new .step file in the appropriate sites directory (e.g., sites/frontend/my_new_step.step) following the format: title, goals, and numbered step blocks (sites/frontend/HTML_structure.step)
2. The step will be automatically indexed by lib/contents.rb on app startup and integrated into lib/site_index.rb navigation (lib/contents.rb)
3. Access the step at /frontend/my_new_step URL; Sinatra routing in app.rb automatically routes the request to lib/step.rb parser (app.rb)

Add support for a new language/locale

1. Create new locale directory locales/LOCALE_CODE/ (e.g., locales/fr/ for French) (locales/en/general.yml)
2. Copy and translate YAML files from locales/en/ to your new locale directory (general.yml, sites.yml, header_sections.yml, captions.yml) (locales/en/sites.yml)
3. Register the new locale code in app.rb request routing logic to serve content at /{locale_code}/path/to/content URLs (app.rb)
4. Add a language flag image and selector link in the header template (lib/html5_page.rb) to enable users to switch languages (lib/html5_page.rb)

Create a new curriculum site/project

1. Create a new directory under sites/ (e.g., sites/my-curriculum/) and populate it with .step or .md files following existing conventions (sites/frontend/frontend.step)
2. Optionally create a site extension module in lib/site_extensions/my-curriculum.rb to customize behavior like custom page layouts or navigation (lib/site_extensions/installfest.rb)
3. Register the site in lib/contents.rb so it is discovered and indexed at startup (lib/contents.rb)
4. Add site title and metadata translations to locales/{en,es,zh-tw}/sites.yml and it will appear in the header navigation (locales/en/sites.yml)

Customize styling for a specific curriculum site

1. Create a new SCSS file in assets/stylesheets/ (e.g., assets/stylesheets/my-curriculum.scss) with site-specific CSS rules (assets/stylesheets/step.scss)
2. Import the stylesheet in assets/javascripts/application.js or conditionally load it in lib/html5_page.rb based on site name (assets/javascripts/application.js)
3. Use semantic class names on content blocks (e.g., <div class='my-curriculum'>) to target your styles without affecting other curricula (lib/step_page.rb)

• Sinatra — Lightweight, routing-first web framework perfect for static documentation sites that need dynamic request handling and URL rewriting without Rails overhead.
• Erector — Ruby DSL for HTML template generation elimin

SITE_LOCALE env var required for non-English: default is 'en'; setting SITE_LOCALE=es serves from sites/es/. Subdomain routing needed for multi-locale in production: must configure DNS/proxy to route es.railsbridge.org to the app with SITE_LOCALE=es (see README). Multiple file formats per course: if both file.step and file.md exist, .step wins; confusing to debug if you edit the wrong one. Erector DSL in some templates: lib/erector_scss.rb uses Erector (Ruby HTML DSL), not standard ERB; unfamiliar to template-only developers. No visible database: all content is file-based; scaling content discovery or analytics requires custom work.

• StepFile Format — Core content abstraction for RailsBridge; lib/step.rb parses custom .step syntax (goals, numbered instructions, tips, etc.) that makes interactive lessons more structured than raw Markdown
• Content Localization via Subdomain Routing — Enables serving multiple languages (en, es, etc.) from the same app instance; SITE_LOCALE env var + DNS subdomain mapping is an elegant pattern for multi-regional curriculum delivery without separate app instances
• Markdown Rendering with Custom Extensions — lib/markdown_renderer.rb extends standard Markdown with RailsBridge-specific syntax (checkboxes, code highlighting, custom blocks); understanding this layer is critical for debugging broken formatting
• Erector HTML DSL — Some page templates use Erector (lib/erector_scss.rb) instead of ERB; a Ruby DSL for building HTML programmatically, uncommon in modern Rails but used here for complex UI logic
• Static Site Generation from Content Files — Core architecture: .step / .md files on disk → Site class tree-walks → lib/*_page.rb renderers generate HTML on request (or could be pre-compiled); no database, simple git-based workflow for contributions
• Site Extensions / Course-Specific Customization — lib/site_extensions/ directory contains per-course hooks (installfest.rb, intro-to-rails.rb); allows different courses to override rendering or add custom logic without forking the main app
• Progress Tracking via Client-Side Checkboxes with MD5 Hashing — assets/javascripts/checkboxes.js + md5.js persists student progress in localStorage keyed by content MD5; clever pattern for stateless curriculum delivery where progress state lives in the browser

• railsbridge/railsbridge.github.io — Official RailsBridge homepage and event listings; companion site to the docs
• railsgirls/railsgirls.github.io — Similar curriculum-delivery approach for Rails Girls workshops; shared philosophy on beginner-friendly technical education
• bundler/bundler-site — Also a Sinatra-based documentation site; peer project in the Ruby ecosystem using similar content-first architecture
• ruby/www.ruby-lang.org — Official Ruby documentation site; uses comparable static-content-plus-rendering pattern for multi-language docs
• alexch/deck.rb — Library referenced in railsbridge/docs for .deck.md presentation slides; used for some RailsBridge workshops

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for lib/markdown_renderer.rb and lib/step_page.rb

The repo has a CI workflow (rspec.yml) but the lib/ directory contains critical rendering logic with no visible test coverage. markdown_renderer.rb converts markdown to HTML and step_page.rb processes step files—both are core to content delivery. Adding tests here would catch regressions in how curriculum content is parsed and displayed across locales.

• [ ] Create spec/lib/markdown_renderer_spec.rb with tests for heading parsing, code block rendering, and link conversion
• [ ] Create spec/lib/step_page_spec.rb with tests for step file parsing, checkpoint detection, and multiple locale handling
• [ ] Verify tests run in rspec.yml CI workflow and add coverage reporting

Add i18n tests for locales/{en,es,zh-tw}/ YAML files

The repo supports 3 languages (en, es, zh-tw) with separate caption and site YAML files. There's no validation that translation keys are complete across all locales or that YAML is valid. A failing locale file could break production. Tests should verify key parity and YAML syntax.

• [ ] Create spec/lib/locales_spec.rb to validate all .yml files in locales/ are valid YAML
• [ ] Add tests to verify all keys present in locales/en/ exist in locales/es/ and locales/zh-tw/
• [ ] Add a Rake task (in Rakefile) to run locale validation that CI can call before deployment

Add tests for lib/site_extensions/*.rb to validate site-specific configuration

The repo has 4 site extensions (docs.rb, installfest.rb, intro-to-rails.rb, javascript-snake-game.rb) that configure different curriculum sites. These have no visible test coverage. A broken site extension could break an entire curriculum path. Tests should verify each site loads correctly and has required metadata.

• [ ] Create spec/lib/site_extensions_spec.rb with tests for each extension in lib/site_extensions/
• [ ] Verify each site extension can be instantiated and has required properties (title, locale, routes)
• [ ] Test that site-specific content directories (e.g., sites/en/installfest) are correctly loaded by each extension

• Add RSpec tests for lib/markdown_renderer.rb: currently no visible spec files in the repo data, and this is the highest-risk rendering code that could silently break markdown formatting. Write tests covering code fence language detection, list nesting, and custom RailsBridge syntax extensions.: Protects against regressions in content rendering; undetected markdown bugs break student experience.
• Document the .step file format in a Markdown guide at docs/STEP_FILE_FORMAT.md: README links to step_file_reference.md (not in the file list), but no canonical format docs visible. Reverse-engineer from lib/step.rb and create a learner-friendly reference with examples.: Lowers barrier for course authors to create new curriculum without reading Ruby code.
• Add missing accessibility labels to assets/javascripts/checkboxes.js: the progress checkbox feature has no aria-label or role attributes; screen reader users can't tell what they're checking. Audit and patch.: RailsBridge serves beginners, many of whom may have accessibility needs; aligns with community values.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.