NepWalk — Decision Log (MVP v2)
Authoritative for shared NepWalk product, technical and team-workflow decisions. Commercial planning is kept outside this repository. Historical IDs are preserved where product specifications depend on them. It overrides older technical documents wherever they conflict.
Rules for humans and AI agents:
- Read this file before planning or building anything.
- If a task conflicts with a decision here, stop and flag it. Don't silently follow the older doc.
- New decision → add a row here first (date, decision, why), then build on it.
- Items in "Open — look at further" are not decided. Don't implement a guess.
Related: requirements.md (MVP requirements) + scope.md (supporting scope, superseded where requirements differ) + tasks.md (build days), created 17 Sep 2026. The founder's business plan is kept outside this repo.
Decisions
Product implications of earlier business decisions
This is a technical extract, not a change to the commercial decisions. Commercial details and superseded business rows are kept outside the team workspace.
| ID | Date | Product constraint | Why engineers need it |
|---|---|---|---|
| B2 | 2026-09-15 | Future payment-flow support is subject to approved product scope; payment functionality is outside the current MVP (P19). | Do not implement future payment work from this historical row alone. |
| B3 / B4 | 2026-09-15 | Superseded or generalized by B12: paid trips use a licensed agency. | Apply the current organization and access rules. |
| B7 | 2026-09-15 | One web app with roles; no separate vendor platform. | Avoid an unapproved additional product. |
| B8 | 2026-09-19 | Bookings belong to trips, which may be personal or organization-owned. Later decisions control delivery and permissions. | Preserve the trip and organization boundaries. |
| B9 | 2026-09-21 | Show clear plans and proper service. Vendor selection depends on service quality, never commission. No public commission disclosure. | Preserve selection and visibility rules. |
| B11 | 2026-09-21 | Support solo travellers, families and groups. The MVP begins with team-created group trips (P19). | Do not hard-code a group-only product. |
| B12 | 2026-09-22 | A licensed agency delivers paid trips; NepWalk provides the platform. The assigned agency is represented by Trip.orgId (T13). The rating suspension policy remains subject to O17. |
Organization boundaries and delivery roles affect authorization. |
| B13 | 2026-09-22 | Commercial settlement terms are kept outside this workspace; no rate is specified for implementation. | Do not infer billing functionality or rates. |
| B14 | 2026-09-22 | The first operated trip uses a founder-approved partner agency. | Do not hard-code partner identities or agreements. |
Product (MVP)
| ID | Date | Decision | Why |
|---|---|---|---|
| P1 | 2026-09-15 | MVP makes the real group-trip workflow easier (trip details are often open at first — only arrival date may be fixed): client context → work out dates and gaps → ask client questions → WhatsApp vendors → record confirmations → send "booked for you" summary. Vendor calls stay human. | Real, repeated pain; next church group arrives 28 Dec 2026. |
| P2 | 2026-09-15 | One itinerary is the baseline. Hotels, flights, transfers and van days are itinerary items (STAY, FLIGHT, TRANSFER, VEHICLE, PLACE, MEAL, FREE, CUSTOM). Rules, bookings, vendor sheets and the traveller view all come from it. Replaces the earlier idea of separate Stay/Move tables. |
Enter everything once; reuses existing Day/Itinerary models. |
| P3 | 2026-09-15 | Operator knowledge becomes tested rules (R1–R10: night coverage, city continuity, transfers, check-in timing, rooms & vehicle size, connection risk, winter fog, missing info, peak dates, headcount not final). Every real miss → new rule + test. | This is the product's advantage, not the forms. |
| P4 | 2026-09-15 | Questions panel is a core operator screen: rule questions + AI suggestions (labelled), with why, category, blocks-booking flag and status; tick → compose one WhatsApp message to the client. | Operator talks to the client; the tool tells him what to ask. |
| P5 | 2026-09-15 | Vendors and places are NepWalk-wide (not owned by an agency). Vendor status: unverified / verified / blocked. | All vendors connect through NepWalk; agencies' own vendors later join as unverified invites. |
| P6 | 2026-09-15 | WhatsApp via wa.me pre-filled links and monospace text blocks. No WhatsApp API in MVP. |
Zero cost, zero approval process. |
| P7 | 2026-09-15 | Acceptance test = an example church-group request (typical shape; the real 2026 trip is not planned yet — only its 28 Dec arrival is fixed): 28 Dec–10 Jan, KTM 5n → PKR 7n, flights 2 Jan and 9 Jan, 1 double + 5 single, van in KTM. Must flag the missing 9 Jan night, 6 rooms / 78 room-nights, 7 services. | Real case beats invented personas. |
| P8 | 2026-09-15 | Cut from MVP: reorder/duplicate/templates UI, agency screens, change approval, version history, push, vendor login, payments, WhatsApp API, AI itinerary generation, reviews, marketplace search, PWA offline, i18n, live alerts. | 2-week solo build. |
| P9 | 2026-09-15 | Headcount can change until enrolment closes. Trip stores pax enrolled / expected max / lock date. Services get an on hold status (range + release-by date) before requested. Rule R10: holds only until locked; lock date before earliest vendor release-by; re-run rooms and vehicle class on every pax change. |
People are still enrolling when trips are planned; peak-season rooms must be held early. |
| P10 | 2026-09-17 | Build day 1 was missed: days 1–2 share Thu 17, later days shift by one, F10 AI assist defaults to October (earlier only if ahead). Launch stays Wed 30 Sep. Scope lives in scope.md; build days in tasks.md. |
Protect launch date without cutting never-cut items. |
| P11 | 2026-09-17 | Frontend base = feat/mvp-base: origin/dev (trip pages, hooks, drag & drop, templates, settings, e2e) merged with design-system (Storybook, design docs, AGENTS.md). Merge, not rebuild. On conflicts dev's button/badge/avatar/input win (hardcoded hex; unify tokens in Oct, O7). Storybook stories excluded from type-check until updated. |
The trip pages already existed on dev; the merge built cleanly in ~40 min. |
| P12 | 2026-09-17 | Local dev DB is created from template0 (CREATE DATABASE nepwalk_db TEMPLATE template0) because the machine's Postgres templates have a collation-version mismatch. Seed logins: admin@nepwalk.com / password123. |
Unblocks local testing without changing system databases. |
| P13 | 2026-09-17 | Read rule: a trip and its days/itineraries are readable by its creator and members (active or invited); anyone else only when the trip is public; otherwise 404. Non-members never receive member/creator emails. Templates are visible/usable by their owner or when the trip is public. Reorder must list every itinerary of the day exactly once. Implemented in nepwalk-be/src/modules/trips/trip-access.ts. |
Closed the audit's data leaks without adding roles. |
| P14 | 2026-09-17 | One branch name across repos: feat/mvp-base in nepwalk-fe, nepwalk-be and nepwalk-docs (pushed and merged 17 Sep; later work continues on the same branch after syncing with main). Backend e2e tests run against nepwalk_test only. |
Easy to pair FE/BE work; tests never touch dev data. |
| P15 | 2026-09-19 | No hard time windows. The backend only checks the time format (HH:MM) and that end ≠ start. Night activities, early hikes and overnight travel are allowed. Overlaps become planning warnings, not errors. Later: typical time windows per activity stored as data (e.g. breakfast allowed 05:00–12:00, ideal 07:00–10:00) plus place opening hours, used by AI and rules to suggest normal times while allowing exceptions (backlog). |
Real trips include night clubs, 5:30 hikes and night buses. |
| P16 | 2026-09-19 | Build day 3 (Fri 18) was done on Sat 19 instead; later build days keep their dates. Itinerary.placeId / vendorId move to build day 7, created together with the Place and Vendor tables (real relations, no loose ids). |
Founder chose to catch up on Saturday. |
| P17 | 2026-09-20 | The nights strip goes; the check stays. Instead of a bar across the top of the trip screen, each day shows its stay inline (the hotel card, or "+ Add hotel" when there is none — the Visitacity pattern), and a connector between days carries a city change with Add flight / Add drive when no move is planned. Night coverage and city continuity stay in the rules (R1, R2) and surface as those inline prompts and as questions. The derived logic (nights.ts) and its tests are kept. Lands in build day 6/7, once the rules produce real output. |
The founder found the strip poor UI and a second mental model; the gap should appear where the work happens. Building the UI once against real rule output beats building it twice. |
| P18 | 2026-09-20 | Trip setup moves into a right-hand drawer on the trip screen, for the creator only. Group size (enrolled / expected max / lock date), room mix, leader contact and dates are setup, not a separate settings page. Nobody but the trip creator sees the drawer or its button — no read-only version for organisation members. The backend already hides leader contact from non-insiders, so this is presentation, not access control. | Setup belongs next to the itinerary it configures; other viewers have no reason to see operator fields. |
| P19 | 2026-09-21 | MVP redefined around the traveller's day plan (requirements.md, M1–M12). The hero is the day plan with Nepal's culture, in the Visitacity pattern; the NepWalk team builds trips from ready-made itineraries; the leader gets a view-only share link. Out of the MVP: prices, payments, vendor directory/portal, auto-selection, booking tracker, WhatsApp drafts, commission ledger, questions panel, AI. Bookings stay on WhatsApp; money in a sheet. Supersedes scope.md F3, F4, F6, F7, F8 for the MVP and narrows P1 (the operator workflow becomes the team side, behind the plan). |
The founder wants a product he can show with pride; validation is whether the itinerary and flow work, not whether money flows in the app. |
| P20 | 2026-09-21 | Places are real data, not free text: type (base town, area, sight, experience, airport, hotel), lat/long, parent (Thamel → Kathmandu → Kathmandu Valley), aliases (KTM = Kathmandu), story, tip, typical duration, photo + credit. Rules compare bases, not typed city names. ~30 places at launch (Kathmandu, Pokhara, Chitwan). (Experiences moved out of the place library by P31.) Designed so an AI resolver can map free text to a place later. | "City" as free text gave false alarms (KTM ≠ Kathmandu, Thamel ≠ Kathmandu); lat/long gives travel times now and maps later. |
| P21 | 2026-09-21 | Confirmation = one line per trip, not a badge per stop: "All set ✓" or "N things still being confirmed", tap for the list. | Per-stop status would be daunting for the leader. |
| P22 | 2026-09-21 | Ready-made itineraries: three at launch — Kathmandu 3 days · Kathmandu + Pokhara 7 days · Kathmandu + Pokhara + Chitwan 10 days. Working name "Paila" (पाइला, footstep) — not "package". | Enough to cover the church trip and show range; "package" implies a fixed product NepWalk doesn't sell. |
| P23 | 2026-09-21 | NepWalk handles domestic logistics only. Hotels, vehicles, domestic flights, guides, meals and experiences inside Nepal. International flights and visas stay with the traveller: the trip starts at arrival in Nepal and ends at the airport drop. International only much later, and only on demand. | Where NepWalk adds value and holds vendor relationships; international ticketing is a different business. |
| P24 | 2026-09-21 | A trip in 3 clicks. (1) Type the request — "5 days in Kathmandu and Pokhara", matched without AI from the number of days and town names/aliases — and pick one of the popular Pailas shown, ranked by popularity and the group's preferences; (2) tune it: days, people, preferences, and which services to include or skip (hotels, vehicle, domestic flights, guide, meals & culture); (3) Create. Arrival/departure times, room mix and dietary needs are added later. MVP: every service slot and its size are automatic (hotel nights and rooms, vehicle class from people + luggage, flight seats); the NepWalk team attaches the actual vendor before the trip is shared. Automatic vendor ranking stays post-MVP (refines P19). Trips can also start from scratch; "plan it with AI" comes after launch. | The founder's core promise: everything set in a few clicks, easy as a cake. |
| P25 | 2026-09-21 | Maps inside the itinerary: a map button on each day (numbered stops and tonight's hotel, placed from real coordinates, "Open in Google Maps") and a whole-trip map from the overview. The live app draws them on OpenStreetMap data (tiles: T19). | Travellers want to see where they are going, on the day they are going there. |
| P26 | 2026-09-21 | The team edits everything in a trip: add a stop from the place library, edit its time and title, remove it (with undo). Applies equally to trips built from a Paila or from scratch. Trip setup (leader, dates, group) belongs to each trip (P18), so many trips from many leaders sit side by side. | Pailas are starting points, never fixed packages. |
| P27 | 2026-09-21 | (Choosing is no longer admin-only: the trip creator chooses too — P46, 2 Oct.) A minimal, admin-only vendor list returns to the MVP. For each included service (hotel per town, vehicle, domestic flight, guide, meals & culture) the team chooses from NepWalk's verified list; the first entry is the "NepWalk pick" for that group size. Each vendor: name, type, area, capacity, verification (licence / green plate / driver licence, checked by and when). Still out: vendor portal, self-registration, ratings and reviews, automatic ranking. Partly reverses P19's cut of the vendor directory. | The founder wants the admin to pick vendors, not just switch services on or off; this is the mechanism P24 relies on and where the verified-vendor promise starts. |
| P28 | 2026-09-21 | Travellers never see booking status. The one-line confirmation (P21) is for the NepWalk team and the group leader only; travellers see a calm plan with simple information where it helps ("we meet you at arrivals"). Amends P21 and M5. | Travellers should feel free, not manage bookings; that is the leader's and NepWalk's job. |
| P29 | 2026-09-22 | NepWalk admins approve every vendor, whichever agency uses it. Proof is checked before a vendor can be chosen (licence, green plate, driver licence, registration); the standard is NepWalk's, not each agency's. Extends P27. | Keeps the verified-vendor promise even when agencies run the trips — the stranded-van story happened through a middleman. |
| P30 | 2026-09-22 | Plan, payments, reviews and agency–traveller contact stay on NepWalk. Agencies reach their travellers through NepWalk (in-app calls and messages after the MVP; WhatsApp until then, A6). The product must be easy enough that both travellers and agencies prefer it to going around it. | Keeps the relationship and the record on the platform, and makes leaving it pointless rather than forbidden. |
| P31 | 2026-09-23 | Places and activities are separate. The place library holds places only: towns, areas, sights, airports. What people do at a place (jeep safari, cooking class, paragliding, cultural dance dinner, canoe ride) is an activity, and one place can have many; activities are modelled after launch. Until then such items go into a trip as ordinary itinerary items (meal / custom). The EXPERIENCE place type stays in the schema, unused. Sights carry a typical visit time as a guide, not a limit; towns and areas have none. Place photos use free licences only (CC BY, CC BY-SA, CC0, public domain) with the credit shown. PKR means Pokhara city. Amends P20 and M2. |
People visit places and do things there; mixing the two made "experiences" look like places and fixed times on areas like Thamel made no sense. |
| P32 | 2026-09-24 | At launch every trip is a personal trip (orgId empty, T13), including the church trip, which sits under the founder's account. Organisation trips (the assigned agency as the trip's organisation, B12) wait until the partner-agency agreement is signed (O4, Fri 30 Oct); no API to create organisations or add members before launch. |
Nothing to build for the MVP; the organisation model is already in the database for when an agency actually joins. |
| P33 | 2026-09-24 | The leader's basics (M10) are fixed lists. Arrival and departure flights are trip fields (flight number + time with its UTC offset), not itinerary items. Pace: Relaxed · Balanced · Packed (stops per day). Interests: culture, spiritual, nature, trekking — more (adventure and others) after research (O21). Budget level: budget · standard · premium. All are team-only: hidden from anyone outside the trip, like the leader's contact. | Fixed values can rank Pailas (P24) and later pick hotel class; two pace levels were too coarse. |
| P34 | 2026-09-27 | Meals and activities are suggestions, not bookings — for now. NepWalk suggests where to eat and what to do (jeep safari, canoe ride, Tharu dance…); travellers choose and pay themselves, so meals and activities get no service slot and no vendor. The P24 service "meals & culture" is dropped: the services are hotels, vehicle, domestic flights and guide. No offers, discounts or partner deals until the system is ready. Booking activities properly comes back later (O23). Amends P24 and P27. | Fix the core first; activities matter for the experience and deserve proper design, not a quick slot. |
| P35 | 2026-09-27 | One vehicle and driver for each road stretch. The group keeps the same vehicle and driver for every place it reaches by road (Kathmandu → Pokhara → Chitwan by road = one vehicle all the way). A town reached by flight gets its own vehicle (fly to Pokhara = one Kathmandu vehicle + one Pokhara vehicle). Change the vehicle only for an urgent reason. One service slot per stretch, from its first day to its last. Refines R5. | The driver gets to know the group, wins their hearts and earns their tips; one vehicle per day would change drivers for nothing. |
| P36 | 2026-09-28 | Who edits a trip ("team"). Until the agency onboarding: only the trip creator edits; everyone else (group leader, travellers, other signed-in users) sees the view-only plan (frontend canEditTrip). From the agency onboarding (October): members of the trip's organisation (Trip.orgId, the assigned agency — B12) edit, everyone outside views only; the backend trip-member role LEADER is then renamed (e.g. EDITOR) so it is never confused with the group leader, who never edits (M5). |
Launch has one editor (the founder), so creator-only is enough and already built. An agency with several staff needs all of them to edit the trips it delivers. Today the backend calls the editor LEADER, which is also the product's word for the view-only group leader — a naming trap that could give a pastor edit rights. |
| P37 | 2026-09-28 | (Coordinates: superseded by P39 — maps and directions are public.) Place data has three tiers. (1) Public — anyone with a link, signed out or not in the trip: a place's name, type, photo + credit and a one-sentence teaser; no story, tip, duration or coordinates. (2) Trip insiders (creator, trip members, the trip's organisation): what the day plan shows — story, tip, duration, map position. (3) System admin (SystemRole.ADMIN): everything. No public list or search of places (search needs sign-in); the public place route is rate-limited. Public trip reads use tier 1 for every stop's place. |
The place library is NepWalk's own data (M9); it must not be collectable by curling public pages or walking public trips. Found 28 Sep: public trip reads returned every stop's full place (story, tip, coordinates) to signed-out visitors — fixed the same day (nepwalk-be 89c9f3b, nepwalk-fe de371a0). |
| P38 | 2026-09-29 | The right-side drawer is the day plan's quick-action layer. The day answers "what is going on and what should I do". Tapping something on it — tonight's hotel (more actions), the vehicle (where it is coming from), the word of the day, and more later — opens a drawer from the right with quick information and actions, with tabs when one thing needs several. Detailed work goes to its own page or popup. The traveller should barely leave "my day, today". Built up gradually: the first use is the word of the day's "Learn more" (M2, 29 Sep); new day-plan details go into the drawer rather than new pages. | Founder: keep the day simple and make the drawer a strength — one place for quick actions instead of scattering screens. |
| P39 | 2026-09-30 | Maps and directions are public. The public trip preview and public place links show a library place's map position and "Directions"; story, tip and duration stay for trip insiders. Private stops (P41) never appear publicly. Partly supersedes P37 (coordinates only). | Travellers post where they are going; sights are on every map anyway, so hiding them protects nothing. The written content is what P37 still protects. |
| P40 | 2026-09-30 | (Public preview and Publish superseded by P45, 1 Oct.) Sharing at launch has two views (M5): a public preview (title, days, towns, public map, short description) and a private trip link — a secret, revocable, view-only link the creator shares with the group, showing the full trip including private stops, never contacts, emails, prices or booking status. Join requests (a traveller asks from the preview, the leader accepts, the traveller then sees the full trip) are built right after launch, in October. | The church group leader posts tomorrow's plan into Facebook Messenger every evening by hand (three real samples, 30 Sep); the group opens links without a NepWalk account. Join requests need traveller accounts and a leader approval screen (~2–3 days) that launch week can't hold. |
| P41 | 2026-09-30 | Private stops for sensitive places. Churches, nutrition centres, orphanages, schools and similar places a group visits are trip-only stops: never in the shared place library, the public preview or a public map; visible to trip members only (the private trip link now, accepted members later). | Safeguarding: places where children are must not be findable from a public page. Groups bring their own ministry partners; these are not tourist places. |
| P42 | 2026-09-30 | "Copy day as text" for the leader: one tap copies a day in the leader's own Messenger format ("Plan for Thu 31 Dec (Day 3, Pokhara): • 8:00 Devo at Himalayan Java …"), ending with "Full plan and map: |
The church group leader posts tomorrow's plan into Facebook Messenger every evening by hand (three real samples, 30 Sep). Feeding that habit beats replacing it; the link line puts NepWalk in every post, and the footer lets the group know who built it. |
| P43 | 2026-09-30 | Soft rule R11 — end in Kathmandu with a buffer: a warning (never a block) when the last night before the international flight is not in Kathmandu, or a domestic flight or long drive falls on the departure day. Pailas may go Pokhara first and Kathmandu last. | Fog and delays on the Pokhara–Kathmandu leg can miss the flight home; the founder wants a nudge, not a hard rule. |
| P44 | 2026-10-01 | Template read rule: owner or public. Anyone may read the template of a public trip; the template of an unpublished trip is read by its creator only. Trip members and organisation members do not see it, so the rule is narrower than the trip read rule (canViewTrip) on purpose. One helper holds it (template-access.ts); list, detail, match, apply and create-trip all use it. Revisit when agencies share their own templates inside an organisation. |
Moving templates to the trip read rule would have widened access six days before launch, and nobody needs it: Pailas are public and no organisation is in use yet. One helper still removes the second, drifting access check (S1). |
| P45 | 2026-10-01 | Sharing is one link, one step. The creator taps Share: the trip's link is shown in a popup with Copy (and the phone's share menu); the right drawer (P38) stays for hotels and other trip management. A trip is private until then; after that anyone holding the link sees the full view-only plan. The popup has one switch: on = anyone with the link can view; off = private again and the link stops working at once (DELETE /trips/:id/share-link); turning it on again brings the same link back, so the leader never has to re-send it. No Publish on the trip page or in settings, no public preview page (/t/<slug>), and no "Make a new link" control in the app; the backend can still replace a leaked link (POST /trips/:id/share-link/rotate, S7), and a replaced link never comes back. Trips made public earlier keep a "Make private" action. Supersedes P40's public preview and the Publish step; join requests (P40) need a new entry point and are re-planned after launch. |
Founder review of the first share sheet, 1 Oct: publish and share as two things, plus link replacement, were too heavy for a leader who only wants to send the plan to the group. |
| P46 | 2026-10-02 | The trip creator chooses the vendors. For each service of their own trip the creator picks from NepWalk's verified vendors that fit (admins keep a short fixed list, 2–5 hotels per town); the NepWalk pick is first. The choice is offered right after the trip is created and on the Services page afterwards. The creator sees a vendor's name and town only — never phone, proof or capacity — and cannot add vendors. NepWalk still books and confirms: the creator sees "still being confirmed" / confirmed, and a confirmed service is locked for the creator ("ask NepWalk to change it"). After launch: a notice to the admin when a creator chooses, then booking through hotel APIs and portals. Amends P27 (choosing was admin-only) and M12 (the line was team-only); shared-link viewers still see no booking status (P28). | Guided control for the creator, and the admin no longer has to pick every hotel afterwards. A leader who creates a personal trip should shape it without waiting for NepWalk. |
| P47 | 2026-10-02 | Services are a few choices, not a list of slots. The creator chooses one hotel per town, one vehicle per town, one airline for the flights and one guide for the whole trip; each choice is saved for every slot it covers, all or nothing. Everything comes pre-selected with the NepWalk pick and one "OK" saves it all (founder, 2 Oct evening; replaces the "Use NepWalk picks" button); nothing is saved before OK. Tabs — All · Hotels · Vehicle · Flights · Guide. "All" opens first and shows every choice in brief with the vendor selected; the other tabs hold a dropdown per choice to pick another vendor. The button is "Save selection", outlined (drawer actions are outline buttons — nepwalk-fe/design-system.md). A guide is no longer tied to one town (like an airline), so the same guide can stay with the group. The confirmation line (P21) counts choices, not slots. No counts on the tabs. Refines P46 and P27's fit rule. |
Founder: choosing must take two or three clicks; a 7-day trip had 12 slots (6 of them guide days) and a guide who knows the group is better than a new one each day. |
| P48 | 2026-10-04 | Service slots after an edit (founder review of the re-plan, nepwalk-be #29). (1) A moved start date clears every confirmation; every chosen vendor stays. This includes a guide day that lands on a date that was already confirmed. (2) One hotel per town is the default, not a hard rule (refines P47). A new slot takes the vendor of the earliest slot in its choice that has one. (3) An empty list of included services means all four (hotel, vehicle, flight, guide); "chose no service" is not stored in the MVP. (4) Bags and the included services are set when the trip is made; changing them later comes after launch. The setup drawer (P18) shows the start date, the people and the leader's basics only. (5) "Save selection" keeps the drawer open; a "Saved" message confirms it. | A moved trip is a new ask to every vendor: a confirmation given for a Pokhara day showed on a Kathmandu day. A trip with no service has no reason to be in NepWalk for the MVP, and storing that choice needs a schema change three days before launch. The next step after saving (confirm, copy for the leader) is in the same drawer. |
| P49 | 2026-10-24 | Two ways to join a trip (v1). (1) Join request from the shared link: a signed-in person taps Join; the trip appears in their "Shared with me" with a Pending status and stays view-only (what the shared link shows) until the leader accepts or rejects it. (2) Email invitation from the leader: the leader invites people by email; signing in with that email (verified, or Google) through the invite enrols them directly as traveller members, no approval step. Invite links are personal, expire and can be revoked; a different email than invited becomes a normal join request. The leader can remove any member. Expected main use for the church group: join requests. Delivers the join requests of P40 in v1; sharing stays one link (P45). | The leader keeps control over who is in the group, without blocking anyone from seeing the plan; direct invites save the leader approval work for people they already know. |
| P50 | 2026-10-25 | Planner v1 (card docs/v1/features/planner.md, builds on M7). Signed-out visitors plan freely; the first edit or Create trip asks to sign in. More Pailas written by the founder with AI as seed data (Kathmandu, Pokhara, Chitwan alone and mixed in several lengths; Bhaktapur, Lalitpur, Nagarkot visits; mission-trip Paila); an admin screen for Pailas is v2. Pailas carry interest tags and pace, used for ranking and filters; budget later. A service can be Not needed for real (saved, not sent to the admin). Pace words: Relaxed · Balanced · Full. Arrival and departure flights optional at creation; airport buffers 3–4 h international (default 3 h 30 min) and 2 h domestic, as settings; live flight-delay tracking later. No price in v1: creating sends the admin a notice; the admin arranges and confirms each service (M12). |
Lets anyone try NepWalk without a wall, gives enough Pailas to match real requests, and keeps prices out until hotels and services are onboarded. |
| P51 | 2026-10-25 | Trip day plan v1 (card docs/v1/features/day-plan.md, builds on M1, M2, M13). The planner preview is this same day plan, read-only; first edit asks to sign in. Trip start and end replace flight-only arrival (updates P50 item 5): flying (airport buffers 3 h 30 international, 2 h domestic, as settings), by road (town and time, no buffer) or already here; no time gives a free morning or evening with a prompt. Services not needed read "your own transport" and "Tonight: your own stay · |
Works for every way a trip starts and ends, including future domestic travellers; groups arranging their own services can still get help from NepWalk; real visit times differ hugely by place (Pashupatinath up to 8 h, Lumbini more than a day). |
| P52 | 2026-10-25 | Plan editor v1 (card docs/v1/features/plan-editor.md, builds on M7 revision 2). Create trip is never locked: adults default to 2 and are editable; any edit follows the existing rules (signed out: sign up first; then a draft); dates are still asked when Create trip is pressed. Drafts stay on the server. A longer range adds "Free day in |
Fewer blocked moments before a trip exists; trips include the traveller's own places; one clear send action; the editor keeps hand edits safe. |
| P53 | 2026-10-26 | v1 is the leader's whole journey, complete on stage by Sun 15 Nov 2026 (v1 flow and deadline). In v1: (1) sign up and sign in, help page; (2) a trip from a Paila with the exact group size; (3) the leader accepts NepWalk's vendor picks or chooses others; (4) the admin is notified (in the app, plus a WhatsApp message to the founder, O24); (5) the admin sees every trip in full detail and marks each service confirmed; (6) the leader sees what is confirmed; (7) the leader invites members before everything is confirmed; (8) the itinerary can still be updated; (9) members read the trip day by day, and today's plan opens offline. Place data grows with the Pailas (Kathmandu, Pokhara, Chitwan, plus Bhaktapur, Patan and Nagarkot). Later: My Pailas (last, only if time), install as an app, place page redesign. Milestones: 15 Nov v1 complete on stage · 22 Nov on production, founder walk-through as a leader · 27 Nov first real group ready (the church group's trip made, link sent to the leader; recorded here only, not shown on the dashboard, so the team works to 15 and 22 Nov). If time runs short, cut in this order: plan editor design changes, day plan design changes, joining by link. Niwesh researches popular itineraries and adds places and Pailas as seed data locally with AI, by pull request; the founder reviews, merges and migrates. Things may change on the way; new items go through the founder. | One clear finish line the whole team can see; the church group arrives 29 Dec and needs a working product a month before. |
Design
| ID | Date | Decision | Why |
|---|---|---|---|
| D1 | 2026-09-15 | ("No redesign before real users" superseded by D7, 2 Oct.) ~~No Stitch/Figma redesign before real users.~~ Build straight in code with existing components. Real design system in Jan 2027. | The problem is input and missing info, not looks. |
| D2 | 2026-09-15 | Traveller day view copies Visitacity's patterns: day buttons on top; photo card with time label, title, duration, one line; connector between cards ("🚐 25 min by van"). | Know today's plan in 3 seconds. |
| D3 | 2026-09-15 | Add for groups: "🌙 Tonight: Hotel X" at day end; call/WhatsApp buttons for driver/guide; "⏳ Pending" badge; light fun (countdown, Day X of Y, Nepali word of the day). | What Visitacity lacks and NepWalk needs. |
| D4 | 2026-09-15 | Operator builder: nights strip (whole trip on one line, empty night in red) → one-tap moves between cities → place picker per day. Delete the 7-field Add Activity form ("custom item" as fallback). Remove office wording ("ACTIVE PLAN", "Trip ID", "Publish") and duplicate time display. | Build a 13-day trip in 10 minutes. |
| D5 | 2026-09-15 | Keep the trips dashboard (photo cards) and the green brand. | Already works. |
| D6 | 2026-09-15 | Polish effort goes to the traveller day view; operator screens only need to work well. | The client sees it; it doubles as marketing. |
| D7 | 2026-10-02 | Redesign when it is needed. A screen may be redesigned when its UX needs it, before real users too. The day's build task comes first: design work starts only when that day's task is done, and never moves a build day. Still built in code with existing components and the tokens in nepwalk-fe/design-system.md; a layout change gets a feature card first (A13). Supersedes the "no redesign before real users" part of D1. |
UX is the first thing that decides whether a person uses the app. Finishing the day's task still matters more. |
| D8 | 2026-10-19 | The design spec for a developer is a feature card plus a clickable HTML prototype. The card (A13) holds the problem, the user and the acceptance checks ("tap + → the sheet opens at that slot"); the prototype shows the whole journey (taps, sheets, empty and error states, phone width) with the tokens in nepwalk-fe/design-system.md. The founder confirms the prototype on his phone before the task is handed over. Done = every acceptance check passes on a phone, and the founder reviews the PR. Static SVG only for visuals (logo, illustration, one hero screen), never as the spec for a flow. No Google Stitch or Figma. |
A static picture shows one screen in one state, so developers guess the flow and behaviour. A prototype is quick to make, is tested before anyone builds, and its code can be reused. Heavy design tools cost time the team does not have. |
| D9 | 2026-10-24 | Warm Travel Journey, with quiet luxury restraint. The founder approved concept B (from the 24 Oct design discussion, not stored) and the direction of docs/v1/designs/landing.html: generous Nepal photography, warm neutral surfaces, Satoshi, selective green, and restrained postcard, day-stamp, double-underline and route details. Design for comfortable through five-star travel; no backpacker positioning or implied five-star guarantee. Discovery can be expressive; day plans, forms and confirmations stay clear and composed. Glass is optional and contrast-tested; bento is selective, not the default for comparable Pailas. nepwalk-fe/design-system.md owns the detailed rules; shared visual guide summarises them. Extends D5–D8; preserves approved content, product scope, status meanings and phone-review requirements. Approval updates guidance, not every live screen. Be creative: every page or major screen has one named signature idea and varied composition, never a template of identical rows; creativity never costs clarity (design-system.md → Be creative). |
The founder wants welcoming, creative Nepal travel with dependable planning and a recognisable premium identity. |
Tech & architecture
| ID | Date | Decision | Why |
|---|---|---|---|
| T1 | 2026-09-15 | Keep nepwalk-be (NestJS 11 + Fastify + Prisma 7 + Postgres) and nepwalk-fe (Next 15). No rewrite, no new repos. nepwalk_be_django is abandoned. |
~35% of MVP already exists. |
| T2 | 2026-09-15 | AI reads · code calculates · operator approves. Date math, gaps, rooms and money are never done by AI. | Bookings need the same answer every time. |
| T3 | 2026-09-15 | AI via OpenRouter free models (no Claude API). OpenAI-compatible client, key server-side only; AI_ENABLED, AI_MODEL_PRIMARY, AI_MODEL_FALLBACKS in env; schema-validate output, retry once, else fall back to the form. |
Cost; free models fail or disappear, so the app must work with AI off. |
| T4 | 2026-09-15 | Redact personal data before any AI call (names, phones, emails, passport numbers → placeholders). | Some free-model providers may log or train on prompts. |
| T5 | 2026-09-15 | Log every AI run (AiRun): input, model, output, operator corrections. |
Accuracy score + test cases; how NepWalk's AI improves. |
| T6 | 2026-09-15 | ~~Superseded by T13 (19 Sep).~~ Organization + orgId on Trip, Service, Question, ShareToken, AiRun from Day 1; seed one org "NepWalk Ops"; scope every query. Vendor and Place have no orgId. |
Agencies in 2027 without rewriting queries; also enforces access control. |
| T7 | 2026-09-15 | New backend modules: organizations, planning (pure functions, no DB), questions, vendors, places, services, messages, share, ai. |
Clear boundaries; rules testable in isolation. |
| T8 | 2026-09-15 | Security before real data: guard all read endpoints, enforce isPublic, template ownership, revocable share tokens; traveller view and summaries never include prices, commissions or emails. |
Current endpoints leak private trips and member emails. |
| T9 | 2026-09-15 | Maps: Leaflet + OpenStreetMap. Weather: Open-Meteo. Place photos: own photos or Wikimedia Commons with stored credit. | Free, no billing accounts. |
| T10 | 2026-09-15 | TDD for auth, planning rules and money calculations. | Where mistakes cost the most. |
| T14 | 2026-09-20 | Frontend gets a unit-test runner (Vitest). Planning rules on the FE (nights, bed capacity, item-form validation) live in pure modules under src/lib/ and are TDD'd; components stay thin. Playwright stays for flows. |
Day-4 logic was too easy to get wrong by eye, and Jest e2e only covers the backend. |
| T15 | 2026-09-20 | Automated tests replace repeated manual checking. Layers: Jest e2e = backend contract (the API is not re-tested in Playwright); Vitest = frontend rules; Playwright api project = 5 checks over real HTTP (CORS, refresh, envelope, leaks); Playwright ui project = the critical browser journeys, which set their data up over the API and sign in by injecting tokens. Founder still eyeballs each new screen once. |
Every bug this week was found by hand-clicking the same flows; that time is better spent building. |
| T16 | 2026-09-21 | Mobile-first progressive web app for the MVP: installable to the home screen with an icon; offline later. No app-store app yet. | Share by link, feels like an app, no store review. |
| T17 | 2026-09-21 | (Before launch: superseded by A14 — ping after the MVP.) Cold starts fixed with a free keep-warm ping (every ~10 min) before the leader gets the link; a paid always-on plan ($7/month) once real users arrive. | A ~50 s first load would ruin the first impression. |
| T18 | 2026-09-25 | Google login uses "Sign in with Google" (Google Identity Services, ID token). The frontend's Google button returns an ID token; POST /auth/google verifies it on the backend (signature, audience = our client ID, issuer, expiry, verified email) and returns NepWalk tokens in the response body. The old redirect login (GET /auth/google + /auth/google/callback, tokens in the URL, no state) is removed. Later (backlog): a backend-for-frontend with an HttpOnly session cookie on one shared domain, so tokens leave localStorage. |
Google recommends Sign in with Google for sign-in; we only need email, name and photo. Removing the redirect closes SEC-02 and SEC-03 with less code than patching it (~½ day vs ~1 day). RFC 10017 ranks the backend-for-frontend most secure, but it needs a shared domain (nepwalk.com + api.nepwalk.com) — after launch. |
| T19 | 2026-09-30 | Maps on MapLibre GL + OpenFreeMap vector tiles (positron style), replacing Leaflet + OpenStreetMap raster tiles for M13. The style is trimmed to roads, water, parks and town names: no buildings, footpaths, street names, railways or airports. MapLibre's worker is served from public/maplibre (copied from node_modules on dev and build). Still OpenStreetMap data, so P25 holds. |
Founder review 30 Sep: the raster map was too busy (every house, shop and hotel). Raster tiles can't hide layers; vector tiles can. OpenFreeMap is free, needs no key and allows commercial use; CARTO and Stadia minimal tiles need a paid plan for commercial use. |
| T11 | 2026-09-17 | Secrets and CORS fail closed: the backend refuses to start without JWT_SECRET / JWT_REFRESH_SECRET (and with placeholder values in production); every JWT has a random jti; CORS allows only CORS_ORIGINS or FRONTEND_URL (required in production). |
Removes silent insecure defaults; production must set these env vars before deploy. |
| T12 | 2026-09-17 | Frontend on Next.js 15.5.25 (+ axios ^1.20, npm audit fix). Accepted until October: postcss pinned inside Next 15 (build-time only) and sharp 0.34 (build-time images); fix with Next 16 / sharp 0.35. Hosting: frontend Vercel, backend Render (Docker, migrations on start), database Neon. |
Closed 2 critical RCE advisories; remaining ones need major upgrades. |
| T13 | 2026-09-19 | Organisations are optional. User stands alone; OrganizationMember (user, organisation, role OWNER/ADMIN/MEMBER) lets a user belong to zero, one or many organisations. Trip.orgId is nullable: empty = personal trip (owned by its creator), set = organisation trip (creator must be a member; members of the organisation can read it). The read rule (P13) adds "member of the trip's organisation". "NepWalk Ops" is created for the founder's operator work, not forced on users. |
Free users use NepWalk without a company; a guide may work with several agencies. Replaces T6. |
Process & AI setup
| ID | Date | Decision | Why |
|---|---|---|---|
| A1 | 2026-09-15 | Department AI framework (agent_framework/nepwalk) and Forgeon (forgeblueflow) frozen until spring 2027. Revive the framework only when ≥3 people work in parallel. |
Process overhead for a solo build. |
| A2 | 2026-09-15 | Solo MVP AI setup = one CLAUDE.md per code repo + this folder (decisions.md, scope.md, tasks.md). |
Minimal, current, shareable with the team in Oct. |
| A3 | 2026-09-15 | Old v0/v1 planning was archived and is not current product authority. Removed from this checkout in the 22 Oct cleanup (A17); Git retains the history. | Avoid conflicting instructions. |
| A4 | 2026-09-15 | Team stays on other work until MVP (Tech Everest website, vendor research sheet); onboards in Oct via this folder. | Solo build; team learns the direction first. |
| A5 | 2026-09-17 | Git workflow: every new branch starts from the latest origin/main, with the same name in every repo it touches (feat/…, fix/…, chore/…, docs/…). Never push to main: the founder merges PRs on GitHub as tech-everest with a merge commit (not squash). |
Squash-merged main made feat/mvp-base conflict; Vercel's Hobby plan only deploys commits authored by tech-everest. |
| A6 | 2026-09-20 | All outbound communication stays on WhatsApp until the MVP is out — vendors, the partner agency and group leaders. No founder email workflow, no Gmail drafts, no email automation before launch. After the MVP the system may send email (confirmations, traveller summaries); the founder still talks on WhatsApp. | That is where these people actually reply; email would add a channel nobody reads and work nobody asked for. Fits P6 (wa.me links, no WhatsApp API). |
| A7 | 2026-09-21 | Product definition before more building. Mon 21 – Tue 22 Sep: (1) business requirements — a one-page story, the must-have list with a business reason for each item, the operator journey in 6–8 steps; (2) a clickable prototype of those screens filled with real church-trip data, following the Visitacity pattern. Build resumes only against screens the founder has signed off. MVP launch moves from Wed 30 Sep to about Wed 7 Oct. Built R1/R2 logic is kept on feat/planning-rules, unmerged, until the Place/base model replaces free-text city. |
The founder could not picture the product from the features built so far and rejected two of them (nights strip, settings page). Mentors, vendors and investors need to see the journey, not a feature list. Still a week ahead of the 14 Oct Pokhara room holds. |
| A8 | 2026-09-21 | (Before launch: superseded by A14 — Neon restore check now, backup script after the MVP.) Backups before real data moves to Tue 6 Oct (was Fri 13 Nov): nightly pg_dump + a real restore test before the church trip, with a real leader's name and phone, goes live. |
The rule is "backups before real traveller data" — and that data now arrives with the 7 Oct launch. |
| A9 | 2026-09-21 | Founder-only business scheduling is maintained outside this workspace. | No technical assignment follows from this historical row. |
| A10 | 2026-09-21 | Place content is drafted, then founder-approved: stories and tips drafted from public sources, photos from Wikimedia Commons with credits (settles O6); the founder approves every one. Drafting is tooling, not AI in the product. | 30 places is too much to write from scratch in the timeline; approval keeps the voice and accuracy his. |
| A11 | 2026-09-22 | Business planning, sales, marketing, finances and legal work stay outside the technical workspace. Only approved product implications are shared here. | Separate private business work from technical delivery. |
| A12 | 2026-09-25 | Security rules S1–S28 are mandatory for every backend and frontend PR (docs/guidelines/security.md). The PR template's security section names the rules checked; a rule not met yet is named in the PR and added to tasks.md, never merged around silently. AI assistants read the rules via each repo's CLAUDE.md and check them before every handover. |
The 23 Sep review found privacy, login and error-handling gaps no test caught (SEC-01–04). As the code grows, a written, numbered checklist on every PR is easier to keep than memory. |
| A13 | 2026-09-27 | Feature cards before building. Each MVP feature gets a one-page card in feature cards before its code: who uses it and the job it does, the value (what breaks without it), placement on mobile / tablet / web and why there, states (empty, loading, error, long content, no photo), rules and edge cases, a low-fi wireframe (mobile + web, text/ASCII — placement and flow, not visual design), then Decided / TBD (with a date) / Backlog, and the task breakdown for tasks.md. One 30-minute session per card (draft + 3–6 questions → answers → final card), 1–2 cards a day beside the build. Order before the 7 Oct launch: M1 day plan · M13 maps · M5 share + status · M7 3-click trip · services (M15, R5 — vehicles, bags, hotels) · M10 leader basics; the rest after launch. |
Clear specs give better builds, by hand or by AI (the build day 11 night run finished 4 of 4 from a precise brief). The prototype's day plan showed repeated navigation, a cramped main area and wasted space — design questions, not code bugs. Wireframes settle placement cheaply before code; polished visual design waits for real users. Short, ordered sessions keep it from delaying launch. |
| A14 | 2026-09-30 | Launch without the keep-warm ping and the backup script (plan revisit, 30 Sep). Before launch, two no-code stand-ins: the founder opens the share link about a minute before sending it, so the leader never meets a cold start; and a 10-minute check that Neon's built-in restore history covers the real trip data. The keep-warm ping (T17), nightly pg_dump and a real restore test (A8) move to after the MVP. Partly supersedes T17 and A8. |
No team is joining soon and launch week is full (Tue 6 had six tasks). The stand-ins keep what T17 and A8 protect — the leader's first impression and the real traveller data — at no build cost. |
| A15 | 2026-10-06 | Launch with the backend's open dependency advisories; upgrade in the first week after. npm audit on nepwalk-be production dependencies: 13 high + 5 moderate. Checked one by one against the code (6 Oct): the Fastify schema-validation and HTTP/2 advisories do not apply (validation is class-validator; the server speaks HTTP/1.1 behind the proxy), the NestJS ones need middleware (the app uses guards), the Prisma / mysql2 / hono ones are command-line tooling on a Postgres database, nodemailer gets validated addresses only. One applies in part: X-Forwarded-* spoofing under trustProxy, so a caller may dodge a rate limit; share tokens are 128-bit random, so guessing stays impractical. The clean fix is NestJS 12 with @fastify/swagger-ui 6: an October task, not a change on launch eve. Also from the same check: the API docs are off on a deployed server (API_DOCS=on turns them on locally), and names of the creator and members stay visible on a share link (contacts never, S4). |
A framework upgrade the day before launch risks more than these advisories do for one small group; the automatic fix did not reach the Fastify the server runs and moved Prisma's CLI off the client's version. |
| A16 | 2026-10-19 | The founder moves to strategy, operations and sales; the team builds. Strategy first, then operations and sales. Mon 19 – Tue 20 Oct: the founder fixes the worst UI/UX and journey breaks in the MVP (the three worst named before starting). Wed 21 – Fri 23 Oct: AI setup for the team, so the founder writes tasks (card + prototype, D8) for everyone, the manager included, and reviews the PRs. Not a rule against coding: the founder steps in when someone is sick, away or not delivering, because the whole outcome is his. The team setup builds on A2 (one CLAUDE.md per repo + this folder); A1's framework stays frozen. |
The MVP is live; finding customers is now the bottleneck (agency interviews and group leaders are behind). The founder's time is worth most on strategy, operations and sales. |
| A17 | 2026-10-22 | Technical team workspace: nepwalk-docs is the team AI base; engineers also use sibling nepwalk-fe and nepwalk-be, while managers may use docs alone. The founder assigns work. One task at a time, with manual testing and explicit review before completion; concise daily and closure guidance always shows the next action. Anyone can report bugs or features for founder triage. Retire the old department framework and keep business/marketing outside docs. Shared technical learning supports founder assignments and member-created paths, with individual teach-back summaries. See team workflow and learning. Skills and the static UI are subsequent work (delivered with A18). |
One shared technical workspace, clear ownership and visible learning without private founder data. |
| A18 | 2026-10-22 | Team commitment, backlog picks and the team trek. (1) Each member gives at least 20 hours a week: 15 h work and 5 h learning, logged at the daily closure; the week runs Sunday to Saturday, Kathmandu time. More time is welcome and never asked for; hours earn no points. The founder can mark a rest week (festival, illness, exams) for one member or everyone; a rest week has no target and never breaks a streak. (2) When a member has no active task and no assigned task that can start today, they may pick a task from the founder's backlog that is open to their role. It counts as extra work, follows the same gates, and can be returned to the backlog. (3) Progress is a game, not pressure: XP only for verified contributions (accepted tasks, independent reviews of accepted tasks, understood learning, optional applications, triaged tickets), each awarded once; levels follow the Everest Base Camp trek from Kathmandu to Kala Patthar (progression superseded by A25); badges, a weekly-goal streak and cooperative team totals. No leaderboards, rankings or comparisons between members (comparisons partly superseded by A21: progress and badges are shared). Quality gates and founder acceptance are unchanged. See team trek. | A clear minimum makes plans honest; picking from the backlog uses spare energy without waiting for the founder; a visible, kind game keeps motivation up without rewarding overtime. |
| A19 | 2026-10-22 | Team records live in nepwalk-docs and travel with normal pull requests. One small JSON file per record under docs/team/records/, so pull requests from different people merge one by one without conflicts; there is no separate sharing step. The dashboard saves straight into a connected nepwalk-docs folder (Chrome or Edge); other browsers and the docs site show the records and give the command to record a change through the AI tool. Records are visible to the whole team; the docs site stays behind Cloudflare Access. |
Nothing is hidden inside the team, and docs, frontend and backend are merged one by one, so records should arrive with the docs merge. One shared data file would conflict on every second pull request. |
| A20 | 2026-10-22 | Team overview for the manager and the founder. A Team view shows every member at once: current task and stage, this week's work and learning hours by day, tasks accepted, reviews waiting, blockers, learning progress, camp and last handoff; plus all tasks by stage and all tickets in one place. Engineers keep their own trek and the shared lists (work, tickets, team learning) without the side-by-side member view (since A21 everyone also sees the team's camps, badges and wins on Today). Members always appear in roster order, never sorted by score. | The manager follows the whole team's progress and quality every day; A18's no-comparison rule still protects each member's own view. |
| A21 | 2026-10-22 | Progress and badges are shared on everyone's Today page. Each member sees their own camp, XP, badges and next badge first, then the team trek: every member's camp, XP progress, badges and a tick for a reached weekly goal, plus the team's recent wins. Roster order, no ranks or "top" lists; hours stay personal (the manager and the founder see them in the Team view, A20). The short daily text answer adds one line with the member's camp, XP and badges. Partly supersedes A18 ("no comparisons") and A20 (engineers now see the team's progress). | The founder wants visible progress and badges to motivate the team; celebrating each other's wins does that without a leaderboard. |
| A22 | 2026-10-22 | AI and terminal first; the dashboard is the fallback. Members work like the founder: they talk to their AI tool in a terminal inside nepwalk-docs, paste screenshots and describe what they need; the AI creates tickets (with the pasted screenshot attached), records tasks, learning and the day through node tools/team.mjs. The dashboard stays for viewing and as a fallback. The AI foundations learning path teaches this exact setup (workspace, context, one task, checking AI work and reporting bugs in the terminal, records and branch, learning by explaining), and the AI teaches it. Members read the learning pages in the browser with a Markdown viewer extension. |
The founder works this way and it is the fastest path; one channel keeps records complete; learning our own workflow pays off from day one. |
| A23 | 2026-10-22 | The NepWalk team are warriors. Ranks follow the trek camps: Recruit (Kathmandu), Scout (Lukla), Trailblazer (Phakding), Ranger (Namche Bazaar), Guardian (Tengboche), Vanguard (Dingboche), Champion (Lobuche), Commander (Gorak Shep), Legend (Everest Base Camp), Summit Warrior (Kala Patthar); A25 extends the progression to Everest and Unstoppable. The AI's daily answer, the dashboard and the docs use warrior wording: courage, discipline and teamwork, never violence. The daily answer shows the member's rank, the team's ranks with weekly-goal ticks and the latest win. | The team calls itself warriors; a shared identity makes the game feel like theirs. |
| A24 | 2026-10-22 | The manager accepts P2/P3 work and tests locally. Niwesh may accept finished P2 and P3 tasks of others after their independent review; P0 and P1, reopening and releases stay with the founder, and nobody accepts their own work. Niwesh runs nepwalk-fe and nepwalk-be on his own machine for testing, like an engineer; previews are not the test environment. Partly supersedes A16/A17 ("the founder accepts") for P2/P3. |
Keeps acceptance from waiting on the founder while he focuses on sales; Vercel Hobby previews do not build non-owner commits. |
| A25 | 2026-10-22 | My growth: Everest and Unstoppable. Keep XP-only progression, paced for roughly a year; faster verified progress may reach the summit sooner. Milestone emblems track XP, achievement badges recognise different contributions, and Everest unlocks Unstoppable at 4,000 XP. Each further 500 XP adds a numbered flame without resetting progress. The calibration assumes 80 XP per week, not an observed average or a quota. Existing contribution values, role permissions and quality gates stay in place. The former four-week Unstoppable badge becomes Steady warrior. Moon, Mars and galaxies remain future ideas. See My growth for the curve and requirements. Partly supersedes A18/A23 camp progression. | A meaningful long-term summit with early wins, visible unlock progress and recognition for learning, quality and teamwork. No calendar gate or overtime incentive. |
| A26 | 2026-10-22 | Founder development stays outside team progress. The manager and engineers participate in team XP, badges, milestone emblems, weekly targets, learning progress and daily closure. The founder keeps the planning, assignment, review, acceptance and team-oversight permissions, but personal business learning and progress are kept outside this shared workspace. Preserve account and historical records; exclude founder awards from current progress displays and totals and create no new founder growth awards. Supersedes A18/A21/A23/A25 participation for the founder. | The founder requested a separate private business roadmap while the team game remains focused on teammates. |
| A27 | 2026-10-23 | Stage before main; only main deploys. In nepwalk-fe, nepwalk-be and nepwalk-docs, every branch (task branches and team/<id> records branches) starts from origin/stage and its pull request goes into stage. Niwesh tests the integrated stage locally. The founder merges stage into main with a merge commit when ready (end of day or after review). Only main deploys and is visible: Vercel (app), the API and the docs site; stage and pull requests do not deploy. New feature cards, task and design specifications and HTML designs go under docs/v1/ and are linked from the task. |
One tested integration point before production; nothing half-finished reaches users or the team site. |
| A28 | 2026-10-23 | Everyone merges into stage; Niwesh requests releases; onboarding is claimed once. Updates A27. Each person merges their own pull requests into stage: records once the checks pass, code once the reviewer approved and the checks pass. Niwesh tests stage locally and opens one release pull request stage into main per changed repository; the founder reviews and merges it. Onboarding writes docs/team/claims/<id>.json with the member's GitHub CLI account; the first pull request carries it and a CI check requires it to match the pull request author. Once merged, onboarding as that member from another GitHub account is refused, and one account cannot hold two members. Only the founder changes or removes a merged claim. |
The founder reviews three release pull requests instead of every merge; identity becomes a real GitHub check instead of a local guard. |
| A29 | 2026-10-23 | UX-first product design. Capture raw product ideas separately from vision; discuss one feature or page, inspect competitor journeys, prototype, review on the founder’s phone, then assign engineering work. Use Impeccable and UX Researcher & Designer under existing project rules. Purposeful motion respects reduced-motion settings. The manager may prepare designs when delegated; founder priority, approval and assignment permissions remain. See product workflow. | Preserve ideas without committing to scope, improve usability before visual polish, and make design preparation transferable. |
| A30 | 2026-10-25 | Team build and design flow. Build: feature card and approved design first, then the spec, then the first failing test. Order: API contract, database, backend, frontend. Unit and integration tests are both required. Before the person's manual test, the AI uses the change on local dev as a real user and as an attacker (playwright-cli); this step needs no extra request. Findings related to the task and small to fix are fixed in the task, test first; the rest become tickets with a suggested priority (P0 security, data or main journey blocked; P1 broken for many; P2 friction with a workaround; P3 polish), and the founder confirms or changes it at triage (suggestedPriority, priority on tickets). Design: the AI proposes placement and impact, then offers two or three options for each key text before drawing; the HTML design opens in the browser once after the first build (a new page in a new tab; the root or index page is shown as a link), not after every change; done means the feature card records the approval date and revision. At any step the AI may ask questions, and lists its assumptions under "Assumptions:". Members reach stage and main only through pull requests (merging their own local branches is fine); only the founder may merge his branches into stage directly, and main changes only through the release pull request. Updates A28. See team-work, team-ticket, team-product-design. |
Engineers know what they build before testing it; real-user and attack checks catch problems before review; priority stays the founder's call while the AI does the triage groundwork; words and placement shape the experience as much as layout. |
| A31 | 2026-10-26 | XP is hard to earn: Fibonacci task sizes and a two-year Everest. Task XP is 1, 2, 3, 5 or 8 (8 for the hardest work, about 1 XP per hour with AI and a clear spec; bigger work is split). Review, learning topic, application and ticket earn 1 XP each. Ranks: Lukla 30 · Phakding 75 · Namche 150 · Tengboche 250 · Dingboche 400 · Lobuche 600 · Gorak Shep 850 · Base Camp 1,100 · Kala Patthar 1,350 · Everest 1,600; a flame every further 200 XP. A normal week (15 h work, 5 h learning) is about 15 XP, a push week 20–25, no cap; Lukla takes at least two weeks. Applied before anyone earned XP. game.md |
AI and clear specs let members do more per hour; XP must stay meaningful and not easy to get. |
Open — look at further (NOT decided)
| # | Item | Decide by |
|---|---|---|
| O5 | Which OpenRouter free models; their data policies and daily limits | Oct 2026 (with F10) |
| O7 | Brand colour token unification (#1B5E7B vs "Brand Green") |
Oct 2026 |
| O8 | Vendor confirmation link design | Oct 2026 |
| O11 | Real design system / designer | Jan 2027 |
| O12 | Name for a ready-made itinerary (working name "Paila") | Tue 22 Sep 2026 (prototype sign-off) |
| O13 | Logo source file: only a 131×35 px PNG exists (nepwalk-fe/public/logo/Logo.png); it looks soft on phones. Need the original vector (SVG/AI) or a larger export |
Before launch (Wed 7 Oct 2026) |
| O17 | Agency rating rules: how ratings are collected, the 2-star suspension rule, appeals | Before the first non-partner agency joins |
| O19 | Restaurants and hotels attached to areas (e.g. lunch or dinner at OR2K in Thamel): how they link to places, whether they are vendors, places or both, and how they appear on the day plan | Fri 30 Oct formal revisit |
| O20 | Travel time between stops: estimate from coordinates (distance × typical speed per area) or use a map service; how accurate it must be for the day plan | Before the day plan, Mon 28 Sep |
| O21 | Interest categories for the leader's basics (P33): which to add (adventure, wildlife, food, photography, wellness…), from what US groups ask for and what the Pailas can offer | Fri 30 Oct 2026 (with O3) |
| O22 | Luggage and vehicle size (R5): guests may bring several bags and must be allowed to; when the budget allows, a separate luggage vehicle; revisit the size limits in the code (car ≤ 3 people and 3 bags · Hiace ≤ 10 people and 12 bags · coaster above; bags default to one per person) | Fri 30 Oct 2026 formal revisit |
| O23 | Booking activities (jeep safari, canoe ride, cultural shows, later paragliding and more): how NepWalk books them, verifies the operator and shows them — an important part of the traveller's experience. Until then they are suggestions (P34) | After the core is fixed; review at the Fri 30 Oct formal revisit |
| O24 | WhatsApp notice to the founder when a leader picks or changes a vendor (P53 step 4): which sender (WhatsApp Cloud API with a business number and template messages, or a simpler personal-notice service), its cost and terms, and what the message may contain (trip name and a link only; no traveller data) | Wed 4 Nov 2026 |
Parked ideas — not now
Good ideas deliberately not pursued until the MVP ships and the model is chosen (30 Oct). Revisit at a formal plan revisit, not mid-build.
| Idea | Parked on | Why |
|---|---|---|
| Separate agency billing, accounting and CRM product | 2026-09-22 | Outside the current product scope |
| Add-ons: SIM cards, event collaborations, insurance | 2026-09-22 | Revenue add-ons after there is traveller volume |
| Going global — connecting agencies in other countries | 2026-09-22 | Nepal first; the model travels once it works here |
| Selling anonymised travel insights ("data is power") | 2026-09-22 | Needs volume, consent and Nepal's Individual Privacy Act checked first |
| Loading that teaches — while a page loads, show something about Nepal instead of a spinner: an outline map of Nepal with one area in focus and what it is known for (Mechi → tea), with a small cartoon character doing something there. One fact per load. The founder may choose another idea for loading later | 2026-10-05 | Needs illustrations and a set of checked facts per area; design work after launch (D7). Pages should also load fast enough that it is rarely seen |
Vision
The founder's long-term product vision lives in ../../vision.md. Read it before any product, design or AI decision; the MVP is cut from it.
Review schedule
- Weekly: Friday review — skim open items, add new decisions.
- Formal revisits: Wed 30 Sep 2026 (post-MVP) · Fri 30 Oct 2026 · Thu 31 Dec 2026 · Mon 15 Feb 2027.