feat: add Portable Living Towns (#98)

Author: hyeonsangjeon

AGENTS.md

@@ -39,7 +39,7 @@ CDN import map (Three.js r0.160 via jsDelivr) plus local data, scripts, and modu
 | **`scripts/fork_lineage.py` + `assets/fork-lineage.js`** | Public-only fork source sanitizer plus deterministic six-color crest projection. | Changing generated fork source truth, lineage cards, or the shared crest batch. |
 | **`scholars.js`** | `window.SCHOLARS` roster: POLARIS · VEGA · RIGEL · MIRA · LYRA. | Adding / editing an NPC scholar. |
 | **`assets/world-tree/createRepolisHero.js`** | Procedural World Tree factory imported by `index.html`. | Changing the tree geometry, materials, sockets, or actions. |
-| **`assets/world-tree/world-tree-state.js`** | Pure projection for Chronicle, Silence Ledger, Roots, sap-flow freshness/mode, and bounded star/repo growth. | Changing how generated city state reaches the silent World Tree. |
+| **`assets/world-tree/world-tree-state.js`** | Pure projection for Chronicle, Silence Ledger, Roots, sap-flow freshness/mode, bounded star/repo growth, and portable public-town residents. | Changing how owner or normalized public-town state reaches the silent World Tree and local resident roster. |
 | **`assets/repo-portal.js`** | Pure username/repository parser, route precedence, public projection, canonical Portal URL, and owner-town expansion link. | Changing `?repo=`, accepted GitHub inputs, public traffic truth, or target share links. |
 | **`assets/repo-route.js`** | Pure 2–3 stop route validator, current-catalog resolver, conflict policy, and canonical Repo Route URL. | Changing visitor-curated multi-repo paths or `?route=` links. |
 | **`assets/contribution-quests.js`** | Pure current-owner/catalog issue projector and bounded quest ranker. | Changing Open Source Quest validation, tier priority, or result diversity. |
@@ -49,6 +49,7 @@ CDN import map (Three.js r0.160 via jsDelivr) plus local data, scripts, and modu
 | **`scripts/build_repos.py`** | Rebuilds `repos.json` and `data/city-state.json` from `data/logs/*` traffic + `gh api`. | Refreshing the city data locally. |
 | **`scripts/resident_profiles.py` + `data/residents/`** | Generates sanitized public resident profiles, the boot manifest, and the Worker authority registry. Profile JSON is generated — do not hand-edit. | Changing repository-bound resident identity or Shared/Bound inputs. |
 | **`scripts/smoke.mjs`** | Hermetic static and behavioral regression guards for the city runtime. | Any client feature, navigation, or generated-module integration change. |
+| **`scripts/test-portable-town.mjs`** | Deterministic fixtures for canonical, foreign, empty/archive-only, partial, missing-date, leakage, resident-cap, and zero-request portable towns. | Changing public-town projection or local resident derivation. |
 | **`.github/workflows/refresh.yml`** | "Refresh Repolis data" — daily Action that regenerates `repos.json` and pushes `chore: refresh`. | CI / data-refresh changes. |
 | **`scripts/build-contribution-library.mjs` + `assets/contribution-library.json`** | Generates the in-app **Contribution Library** JSON from the sibling `Hyeonsang-AI-Contributions` README (KO/EN); `index.html` fetches it at runtime. JSON is **generated — do not hand-edit.** Daily via `.github/workflows/update-contribution-library.yml`. | Changing the library landmark's data/source. |
 | **`cloudflare-taxi/`** | **The live AI backend** — Worker `repolis-taxi` (`src/grounded.js`): grounded repo/docs Q&A + in-persona chat. | Grounding / scholar answer logic. |
@@ -126,6 +127,7 @@ zero LLM, zero cost — so run them freely:
 node council/test.mjs        # deterministic Council crosscheck
 node council/test-live.mjs   # live guards + state machine
 node scripts/smoke.mjs       # city/runtime static + behavioral regression guards
+node scripts/test-portable-town.mjs
 python3 scripts/test_city_state.py
 python3 scripts/validate_city_state.py
 python3 scripts/test_fork_lineage.py
@@ -172,6 +174,7 @@ Tested on Node v24. There is no linter or formatter configured — match the sur
 |---|---|
 | Change how a repo becomes a building (height/size/ornaments) | `index.html` (city-build section) + score/rank in `scripts/build_repos.py`; model in [`docs/domain-model.md`](docs/domain-model.md). |
 | Change Repo Portal parsing, target-first loading, cache, expansion, or privacy events | `assets/repo-portal.js` + the repo data/intro/Station/Atelier blocks in `index.html` + `scripts/smoke.mjs`; preserve one repo request before Aha, `trafficKnown:false` for public API data, 15-minute/512 KiB LRU bounds, canonical `?repo=owner/repo&ref=repo-portal`, and [`docs/repo-portal-change-guide.md`](docs/repo-portal-change-guide.md). |
+| Change portable `?user=` / Repo Portal / Station World Tree or residents | `assets/world-tree/world-tree-state.js` + the post-load projection, World Tree, resident, service-boundary, and debug blocks in `index.html` + `scripts/test-portable-town.mjs`; preserve one existing public load, deterministic public-only state, 6/4 desktop/LOW_END resident caps, unknown traffic/memory, and local/solo service closure. |
 | Change Repo Route selection, ordering, share links, recipient progress, or privacy events | `assets/repo-route.js` + `/*REPO_ROUTE*/` in `index.html` + the Repo Route group in `scripts/smoke.mjs`; preserve 2–3 unique current public repos, strict ordered completion, session-only drafts, identity-free telemetry, and no new scene or network work. |
 | Change Open Source Quest search, ranking, repo-house handoff, or privacy events | `assets/contribution-quests.js` + `/*CONTRIBUTION_QUESTS*/` in `index.html` + the Open Source Quests group in `scripts/smoke.mjs`; preserve explicit one-request search, current owner/catalog filtering, three-card/2-per-repo caps, in-memory results, identity-free telemetry, and Star eligibility only after issue handoff. |
 | Change districts, Village Chronicle, passport, or exploration loops | `index.html` + the matching behavioral groups in `scripts/smoke.mjs`. |
@@ -198,7 +201,7 @@ Tested on Node v24. There is no linter or formatter configured — match the sur
 A daily Action turns the owner's **public repos + committed traffic logs** into `repos.json`; included public
 forks may also carry a minimal canonical source record. `index.html`
 turns that array into metric-shaped buildings, topic districts, routes, maps, and exploration progress.
-Residents add named homes, home/work commutes, moods, friendships, haunts, Shared Joy excursions, gatherings, and festivals. The oldest eligible 20% of the bounded active roster can rarely let slip a hand-authored local lore fragment; repositories younger than 90 generated-clock days receive a lightweight construction layer and newcomer voice. Landmarks include the Contribution Library, Chronopolis, Observatory, and imported procedural World Tree. Repo Portal lets one public `owner/repo` arrive before its owner catalog, then reuses the same building and Repository Atelier with truthful public-metadata boundaries. Repo Route lets a visitor hand off an ordered 2–3 house path they actually explored. Open Source Quests connects an explicitly loaded current public issue to its real repo house before GitHub handoff. Every repo also rebinds one reusable Atelier where its data, impact signals, current avatar, and in-room Gitber stay inside the exhibition. Town Growth Replay turns public repo creation dates into a reversible, shareable city history without inventing historical metrics. Gitber/POLARIS and the
+Residents add named homes, home/work commutes, moods, friendships, haunts, Shared Joy excursions, gatherings, and festivals. Foreign `?user=` and Repo Portal towns run the same pure portable projection after their one existing public load, deriving their own era, season, Silence Ledger, Roots, and 6/4-capped local resident roster without owner traffic, memories, services, or extra requests. The oldest eligible 20% of the owner roster can rarely let slip a hand-authored local lore fragment; repositories younger than 90 reproducible-clock days receive a lightweight construction layer and newcomer voice. Landmarks include the Contribution Library, Chronopolis, Observatory, and imported procedural World Tree. Repo Portal lets one public `owner/repo` arrive before its owner catalog, then reuses the same building and Repository Atelier with truthful public-metadata boundaries. Repo Route lets a visitor hand off an ordered 2–3 house path they actually explored. Open Source Quests connects an explicitly loaded current public issue to its real repo house before GitHub handoff. Every repo also rebinds one reusable Atelier where its data, impact signals, current avatar, and in-room Gitber stay inside the exhibition. Town Growth Replay turns public repo creation dates into a reversible, shareable city history without inventing historical metrics. Gitber/POLARIS and the
 scholars (VEGA · MS Learn, RIGEL · DeepWiki, MIRA · Context7, LYRA · Hugging Face) add natural-language
 navigation and grounded answers. Residents hand specialist questions to the right scholar instead of gaining
 their own MCP access. Gitber remains the only all-district traveler: ride observations and Shared-state answers are local, while household memory questions return to the correct repo home. The Passport's local Town Gazette makes daily public-repo changes visible on return. Everything

CHANGELOG.md

@@ -6,6 +6,27 @@ The format loosely follows [Keep a Changelog](https://keepachangelog.com/); date
 This file keeps the current product era (`1.50.0` onward) easy to scan. Earlier releases are preserved in
 [`docs/changelog-archive.md`](docs/changelog-archive.md).
 
+## [1.92.0] — 2026-08-26
+
+### 🌳 Portable Living Towns — public records grow their own local life
+
+- One pure `repolis.portable-town` v1 projection now runs after the existing `?user=`, Repo Portal, or Station
+  destination load. It derives a reproducible era, sparse-history season fallback, #93-compatible Silence
+  Ledger, archived Roots, public aggregates, and a local resident directory from the normalized payload only.
+- Foreign towns receive deterministic names, jobs, personalities, greetings, and real repo-home bindings.
+  Active residents are capped at six on desktop and four on mobile/LOW_END; archived and empty towns create no
+  false resident. Houses keep their labels, silhouettes, colliders, cards, and interactions at every tier.
+- Visitors/views/clones, owner residents, Shared/Bound memory, daily sap, realtime, and grounded knowledge stay
+  explicitly unavailable. Foreign dialogue is rules-based Local by default, and canonical Worker/WebSocket
+  services are closed for the whole portable visit.
+- The existing public repository request remains the only feature-owned API read. No generated JSON, storage
+  key, persistent identity, analytics event, model call, backend, dependency, build step, or binary asset was
+  added.
+- Controlled cold loads keep same-origin requests unchanged (owner 31→31; foreign 27→27) and the foreign GitHub
+  read unchanged at one. Decoded same-origin bytes rise by 32,975 (owner 1,693,307→1,726,282; foreign
+  1,596,458→1,629,433). Portable sap adds zero draws; resident homes stay within the existing 10/6
+  desktop/LOW_END batch ceilings.
+
 ## [1.91.0] — 2026-08-25
 
 ### 📜 Silence Ledger — factual long-idle repository records

README.ko.md

@@ -75,12 +75,13 @@ Repolis는 공개 GitHub 메타데이터와 누적 트래픽을 또 하나의 
 | 스타 | 지붕 장식 |
 | 최근 활동 | 밤에 빛나는 창문 |
 
-레포는 주제별 구역으로 나뉘고 도로, 표지판, 구역 허브, 세계 지도로 연결됩니다. 주인 마을은 누적 트래픽 기록과 GitHub API로 매일 갱신됩니다. `?user=<login>`은 가벼운 공개 마을을 만들고, `?repo=<owner>/<repo>`는 프로젝트 하나를 먼저 불러옵니다. GitHub는 이 공개 API 모드에 방문자·조회·클론 트래픽을 제공하지 않으므로, 건물은 가짜 트래픽 없이 스타·포크·최근 업데이트로 지어집니다.
+레포는 주제별 구역으로 나뉘고 도로, 표지판, 구역 허브, 세계 지도로 연결됩니다. 주인 마을은 누적 트래픽 기록과 GitHub API로 매일 갱신됩니다. `?user=<login>`은 그 사용자의 세계수 기록과 로컬 주민이 있는 가벼운 공개 마을을 만들고, `?repo=<owner>/<repo>`는 같은 projection으로 프로젝트 하나를 먼저 불러옵니다. GitHub는 이 공개 API 모드에 방문자·조회·클론 트래픽을 제공하지 않으므로, 건물은 가짜 트래픽 없이 스타·포크·최근 업데이트로 지어집니다.
 일반적인 보행 거리에서도 한 번에 그리는 건축 LOD가 레포 집의 텍스처 벽과 지붕뿐 아니라 대지, 생울타리, 진입로, 실제 창유리, 셔터, 창턱, 화분, 배수관, 집 등급별 현관·발코니·포티코를 유지합니다.
 
 ## 실제로 살아가는 마을
 
 - **주민은 제자리 반복 동작만 하지 않습니다.** 이름 있는 주민들이 자기 구역을 거닐고, 시간대에 맞춰 생활하며, 기분이 바뀌고, 아끼는 아지트를 찾습니다. 북동쪽 **별빛 주거구역**에는 이름표가 달린 집과 주민색 앞마당이 있습니다. 집마다 3종 지붕 실루엣, 셔터, 트랜섬 창, 선택형 창가 화분·캐노피·굴뚝·지붕 장식이 다르게 조합되고, 공동 꽃정원·랜턴·생울타리·활엽수·사이프러스가 마을을 감쌉니다. 밤이면 따뜻한 창과 현관으로 귀가하고, 아침이면 각자 구역으로 출근합니다. 친구를 알아보고 함께 산책하거나 나란히 쉬며, 모닥불에 모이고, 때로는 새 릴리스 축제를 엽니다. 두 주민은 플레이어 지시나 AI 호출 없이 실제 꽃밭·별이 보이는 밤하늘·실제 레포 집으로 짧은 **함께하는 기쁨** 나들이도 스스로 떠납니다. 전문 질문을 받으면 아는 척하지 않고 맞는 현자를 소개합니다. 나침반을 따라 마을 안에서 그 현자를 직접 찾아가세요.
+- **공개 마을도 자기 기록으로 살아갑니다.** 기존 공개 레포 요청 한 번으로 도시력·계절·고요 장부·아카이브된 The Roots와 데스크톱 최대 6명/휴대폰·LOW_END 최대 4명의 주민을 결정적으로 만듭니다. 주민의 일·인사·실제 레포 집 연결은 공개 필드만 쓰며, 트래픽·주인 주민·Shared/Bound 기억은 알 수 없는 값으로 남깁니다. 실시간 연결과 근거 검색 서비스도 꺼져 있어 두 번째 API 요청이나 모델 호출이 없습니다.
 - **탐험에는 흐름이 남습니다.** 탐험 여권이 집과 명소 방문을 기록하고, 구역 진행률이 남은 곳을 보여주며, 매일 열리는 **마을 이야기**가 한 주민과 그 아지트, 실제로 이어진 레포 또는 구역을 연결합니다.
 - **도시는 실제 기여로 이어집니다.** **오픈소스 퀘스트**는 방문자가 직접 요청할 때만 익명 GitHub 공개 검색을 한 번 실행해 현재 `good first issue`, `help wanted`, 일반 열린 이슈 중 최대 세 개를 고릅니다. 실제 레포 집을 거친 뒤 정확한 이슈로 연결하며, 결과는 탭에만 남습니다. 로그인·토큰·이슈 추적·새 백엔드는 없고, 기존 Star 초대는 방문자가 이슈 열기를 선택한 뒤에만 나타날 수 있습니다.
 - **방문자가 도시의 가치를 증명한 동선을 그대로 건넬 수 있습니다.** 레포 집을 연 뒤 **Repo Route**에 2~3곳을 순서대로 담으면, 수신 링크가 입장 전에 정류장을 확인해 주고 실제 집을 차례로 가리킵니다. 기존 Star 초대는 이 길을 완주한 뒤에만 열립니다. 초안은 세션에만 있고 URL에는 공개 레포 이름만 들어가며, 백엔드·계정·저장 키·렌더 자산을 추가하지 않습니다.

README.md

@@ -75,12 +75,13 @@ Repolis turns public GitHub metadata and cumulative traffic into a place instead
 | stars | roof ornaments |
 | recent activity | window glow at night |
 
-Repositories are grouped into topic districts with roads, signs, hubs, and a world map. The owner town refreshes daily from committed traffic history plus the GitHub API. `?user=<login>` builds a lighter public town, while `?repo=<owner>/<repo>` loads one project first. GitHub does not publish visitor, view, or clone traffic for those public API modes, so their buildings use stars, forks, and update recency without inventing traffic.
+Repositories are grouped into topic districts with roads, signs, hubs, and a world map. The owner town refreshes daily from committed traffic history plus the GitHub API. `?user=<login>` builds a lighter public town with that user's own World Tree record and bounded local residents, while `?repo=<owner>/<repo>` loads one project first through the same projection. GitHub does not publish visitor, view, or clone traffic for those public API modes, so their buildings use stars, forks, and update recency without inventing traffic.
 At ordinary walking distances, a one-draw architectural LOD keeps each repo house's textured walls and roof while preserving its plot, hedge, path, real window panes, shutters, sills, flower boxes, gutters, and tier-specific porch, balcony, or portico.
 
 ## A village that lives
 
 - **Residents have lives, not idle loops.** Named townspeople wander their districts, keep daily rhythms, carry changing moods, visit cherished haunts, recognize friends, stroll and sit together, gather around the campfire, and sometimes celebrate a recent repository release. Their cottages form **Starlight Row** on the north-east edge, with resident-coloured gardens, three roof silhouettes, shutters, transoms, selected window boxes, canopies, chimneys, and roof finials. A shared flower bed, lanterns, hedges, and broadleaf/cypress trees care for the commons. Night brings residents home to warm windows and porch seats, while morning sends them back to their district work. Pairs also choose their own short **Shared Joy** excursions to real flower patches, visible night stars, or a real repo house—without a player prompt or AI call. Ask a specialist question and they introduce the right scholar instead of pretending to know: follow the compass and find that scholar in the world.
+- **A public town lives from its own record.** The one existing public-repository load deterministically supplies its era, season, Silence Ledger, archived Roots, and up to six desktop/four phone-or-LOW_END residents with local jobs, greetings, and real repo-home bindings. Traffic, owner residents, Shared/Bound memories, realtime, and grounded services stay unknown or off; no second API request or model call is made.
 - **Exploration has continuity.** The Explorer Passport records houses and landmarks, district progress shows what remains, and the daily **Village Chronicle** connects one resident to their cherished haunt and a truthful related repo or district.
 - **The city points outward to real work.** **Open Source Quests** makes one anonymous public GitHub search only when the visitor asks, ranks up to three current `good first issue`, `help wanted`, or open issues, and leads through the actual repository house before the exact issue handoff. Results stay in the tab; no login, token, issue tracking, or new backend is involved. The existing earned Star invitation can appear only after the visitor chooses to open an issue.
 - **A visitor can hand off the route that proved the town's value.** After opening a repository house, **Repo Route** can save it to an ordered 2–3 stop walk. The recipient's link confirms the stops before entry, points to each real house in sequence, and offers the existing earned Star invitation only after completion. The draft is session-only; the URL contains public repo names and adds no backend, account, storage key, or render asset.