Merge pull request #63 from tokenhost/issue-62/pr-01-docs-scaffolding

[Issue 62 1/8] Docs scaffolding and sprint contract

Author: snissn

AGENTS.md

@@ -25,6 +25,23 @@ Tests:
 - CI requires `static` and `integration-local` on PRs to `master`.
 - Canonical generated app coverage includes contract and UI scaffold verification.
 
+## Active sprint: Native hashtag indexing + Filecoin image uploads
+
+Source of truth for the current sprint:
+- GitHub issue: `#62`
+- Ticket draft: `docs/tickets/011-native-hashtag-indexing-and-filecoin-image-uploads.md`
+
+Required living docs for this sprint:
+- Work log: `docs/worklogs/native-hashtag-indexing-and-filecoin-image-uploads.md`
+- Working note / spec delta: `docs/spec-deltas/native-hashtag-indexing-and-filecoin-image-uploads.md`
+- Memo / blog draft: `docs/native-hashtag-indexing-and-filecoin-image-uploads-memo.md`
+
+Execution rules:
+- Deliver the sprint as 8 stacked PRs aligned to the ticket phases.
+- AI may prepare PRs, but PRs must not be merged until human approval.
+- The sprint ticket closes only when all 8 PRs are merged.
+- Any platform behavior change in this sprint must either update `SPEC.md` in the same change or be recorded in the working note/spec-delta document before merge.
+
 ## Phase 0 (NOW): Remediation of current snapshot (stability + security)
 
 Goal: make the current builder reproducible, safe-by-default, and testable before deeper rewrites.

README.md

@@ -5,6 +5,17 @@ Token Host Builder is a schema-to-dapp generator framework for EVM CRUD apps.
 Canonical product behavior is defined in `SPEC.md`.  
 Execution backlog and current gap-tracking is in `AGENTS.md`.
 
+## Active sprint
+
+Current sprint source of truth:
+- GitHub issue: `#62`
+- Ticket draft: `docs/tickets/011-native-hashtag-indexing-and-filecoin-image-uploads.md`
+
+Companion docs for the sprint:
+- `docs/worklogs/native-hashtag-indexing-and-filecoin-image-uploads.md`
+- `docs/spec-deltas/native-hashtag-indexing-and-filecoin-image-uploads.md`
+- `docs/native-hashtag-indexing-and-filecoin-image-uploads-memo.md`
+
 ## Legacy template status
 
 - `tokenhost-web-template/` is retired from this repo.

docs/native-hashtag-indexing-and-filecoin-image-uploads-memo.md

@@ -0,0 +1,44 @@
+# Memo Draft: Native Hashtag Indexing + Filecoin Image Uploads
+
+## Working title
+
+Making Token Host feel native for media and discovery: on-chain hashtag indexes and Filecoin-backed image posts
+
+## Purpose
+
+This memo is a living summary of the sprint behind issue `#62`. It is intentionally more narrative than the work log or spec-delta note so it can be reused later as:
+- an engineering summary,
+- a product memo,
+- a release note input,
+- or the basis for a public blog post.
+
+## Problem
+
+Token Host could already model `image` fields and generic query indexes in theory, but two practical gaps remained:
+- image creation/editing still behaved like a raw string field in the generated UI,
+- hashtag-based feeds required app-specific modeling workarounds instead of a native platform primitive.
+
+## Chosen direction
+
+We are addressing the problem at the platform layer:
+- native tokenized secondary indexes for hashtags,
+- native generated-UI upload behavior for `image` fields,
+- and a provider/runner abstraction so Filecoin Onchain Cloud can be used without hardcoding one hosting topology.
+
+## Key design choices
+
+### Platform-first indexing
+
+We are not treating hashtags as a demo-specific relational pattern. Instead, the sprint adds a native tokenized index capability to Token Host so future apps can reuse the same primitive.
+
+### Upload interface over provider detail
+
+The generated UI should only know how to ask Token Host to upload a file and receive a canonical URL/CID. It should not know provider details or runner topology.
+
+### Bounded behavior is part of the feature
+
+For on-chain tokenized indexes, correctness is not enough. The feature is only acceptable if gas and query behavior stay bounded and testable.
+
+## Status
+
+In progress.

docs/spec-deltas/native-hashtag-indexing-and-filecoin-image-uploads.md

@@ -0,0 +1,57 @@
+# Working Note / Spec Delta: Native Hashtag Indexing + Filecoin Image Uploads
+
+Issue: `#62`  
+Ticket draft: `docs/tickets/011-native-hashtag-indexing-and-filecoin-image-uploads.md`
+
+## Purpose
+
+This file is the working note for the sprint and the temporary home for spec deltas that are not yet fully folded into `SPEC.md`.
+
+If implementation changes platform behavior and `SPEC.md` has not yet been updated, that behavior must be described here before merge.
+
+## Current direction
+
+### 1. Native tokenized query indexes
+
+Working direction for this sprint:
+- extend THS query-index modeling in a backward-compatible way,
+- preserve `indexes.index: [{ field }]` as equality index behavior,
+- add an opt-in tokenized index mode for supported `string` fields,
+- ship one tokenizer in v1: hashtag extraction.
+
+### 2. Upload architecture
+
+Working direction for this sprint:
+- generated UI should depend only on a stable Token Host upload interface,
+- Filecoin Onchain Cloud should sit behind that interface as one provider implementation,
+- runner choice should remain a deployment concern rather than a schema concern.
+
+Initial runner modes under consideration:
+- `process`
+- `remote`
+- future `worker`
+- future `sdk`
+
+### 3. Boundedness and gas predictability
+
+This sprint adds the following requirement beyond the current explicit spec text:
+- tokenized index generation must define hard limits so write gas stays predictable in practice.
+
+Planned bounds to make explicit in implementation and then fold into `SPEC.md`:
+- maximum tokens extracted per indexed field on create/update
+- maximum token length
+- maximum page size for token/equality accessors
+- maximum list scan depth
+
+## Open questions
+
+1. Should tokenized index options live directly in `indexes.index[]`, or should the schema split equality and tokenized index families more explicitly?
+2. Should bounded limits be configurable per chain, fixed by generator version, or partly configurable with hard caps?
+3. Should upload runner mode live in manifest extensions, local preview config, generated app env, or a combination?
+4. Should local-dev chain selection and fallback behavior be codified in `SPEC.md`, CLI docs, or both?
+
+## Merge rule
+
+Before merging behavior that depends on any unresolved item above:
+- either resolve it in `SPEC.md`,
+- or replace the open item here with a concrete written rule and corresponding tests.

docs/worklogs/native-hashtag-indexing-and-filecoin-image-uploads.md

@@ -0,0 +1,46 @@
+# Work Log: Native Hashtag Indexing + Filecoin Image Uploads
+
+Issue: `#62`  
+Ticket draft: `docs/tickets/011-native-hashtag-indexing-and-filecoin-image-uploads.md`
+
+## Purpose
+
+Chronological execution log for the platform-first microblog workstream. This file records:
+- decisions,
+- shipped changes,
+- validation evidence,
+- follow-ups and open risks.
+
+## Entries
+
+### 2026-03-23
+
+#### Planning and sprint freeze
+- Opened GitHub issue `#62` from the local ticket draft.
+- Confirmed the sprint source of truth is the GitHub issue plus the in-repo ticket draft.
+- Confirmed implementation will proceed as 8 stacked PRs and must not be merged by AI without human approval.
+
+#### Architecture direction frozen
+- Chose platform-first implementation over app-specific workaround.
+- Decided not to model hashtags primarily as `Tag` / `PostTag` collections.
+- Decided to add native tokenized secondary indexes in THS/generator/runtime.
+- Decided generated UI must treat `image` as a first-class upload field rather than a raw string input.
+
+#### Upload architecture direction frozen
+- Decided generated UI will talk to a stable Token Host upload interface.
+- Decided Filecoin Onchain Cloud is one upload provider implementation, not a special-case UI path.
+- Decided the provider implementation must remain runner-agnostic:
+  - `process`
+  - `remote`
+  - later `worker`
+  - later `sdk`
+- Decided the default funding model for the Filecoin Onchain Cloud provider is `appPays`.
+
+#### Performance and boundedness requirements frozen
+- Decided bounded token/scan behavior is a release requirement, not a nice-to-have.
+- Planned explicit gas/perf validation rather than relying only on algorithmic reasoning.
+
+#### Next steps
+- Add sprint scaffolding docs and backlog references.
+- Extend THS query-index shape for native tokenized indexes.
+- Implement equality indexes before hashtag token indexes so the generator surface stays layered.