[P0][Onboarding] Connect repository → persistent project context → first useful opportunities

[Ankit6149]

2026-10-04 reconciliation status

Status: ACTIVE / PARTIALLY IMPLEMENTED — remains a GP2 onboarding outcome.

Already present in the repository:

• durable GitHub SourceConnection and event ingestion foundations;
• versioned ProjectContext persistence/adapters;
• hosted ContentSignal / ProjectContext / ContentOpportunity composition;
• owner opportunity/planning/review routes.

Still required for this issue to close:

• first-time connect/provide repository flow proven end to end;
• bounded project bootstrap with exact provenance;
• useful initial canonical opportunities (including truthful “none”);
• Not now preserving context;
• later meaningful GitHub Signal reusing the eligible ProjectContext automatically;
• current privacy/revocation/reopen acceptance.

Do not build a separate onboarding suggestion store. The closing proof must converge on the same Signal → ProjectContext → Opportunity → Today/Plan path used by GP2.

---

Parent outcomes

• [EPIC] Beginner-first hosted experience and low-attention owner workflow #56 beginner-first/low-attention owner experience
• [EPIC][Product Brain] Content intelligence, identity, editorial automation, and low-attention publishing #150 content-intelligence product brain
• [P0][GitHub Signals] Add GitHub App/webhook event ingestion into canonical ContentSignals #161 GitHub connected-source ingestion
• [P0][Golden Path 2] GitHub work event → ranked opportunity → automatic evidence/media-ready campaign #167 Golden Path 2

Product problem

A first-time user should not need to understand SignalFlow's internal concepts (signals, event families, trigger rules, model routing, campaign setup) before the product becomes useful.

The intended first-source experience is:

connect one GitHub repository
  ↓
SignalFlow builds bounded, provenance-backed project understanding
  ↓
incorporates optional user-provided files/links/notes as project context
  ↓
finds a few genuinely worthwhile initial ContentOpportunities
  ↓
owner judges: start here / something else / later / not now
  ↓
project context persists
  ↓
future connected GitHub events automatically reuse that context

Not now is a valid judgment. It must not discard project understanding or force the user to repeat setup on the next event.

Core product invariant

Connecting a supported repository once should enable the default supported source observation automatically. Normal users must not have to configure webhook/event triggers manually.

Advanced source controls may later allow pause, repository scope, event-family overrides, privacy choices, or revocation, but the safe default is:

connect once → SignalFlow notices meaningful supported work → prepares judgment

This issue does not implement automatic posting.

Project context is durable product state

Do not hide project understanding inside one prompt or transient onboarding component.

Introduce one canonical versioned project-context aggregate/snapshot (final naming should follow existing domain conventions after implementation review) that can answer, with bounded provenance:

• what the project is;
• current product/problem framing;
• major capabilities/areas;
• likely users/audiences when evidence supports it;
• terminology/product names;
• current maturity/stage when supportable;
• important architecture/product constraints;
• safe known claims;
• unresolved/uncertain facts;
• source/evidence refs used to build this version;
• repository identity + revision/context version;
• optional owner-provided supplemental context;
• privacy classification;
• created/updated/version identity.

Project context is not Person Identity/Voice. Compose later as:

Person Identity / Voice / Boundaries
+ Project Context
+ exact Signal evidence
+ NarrativeMemory
→ Opportunity / NarrativeStrategy

Repository bootstrap

“Understand the repo” must not mean blindly sending an unrestricted private repository to a remote model.

Bootstrap should use the canonical repository/source boundary to build a bounded representative evidence plan. Prefer high-signal material such as, where present and authorized:

• README/product docs;
• package/app manifests;
• architecture/product documentation;
• route/module inventory;
• recent relevant changelog/release context;
• selected representative source files discovered through the repository planner;
• safe repository metadata.

The planner may traverse the repository structure broadly to understand it, but model/task payloads remain minimized, privacy-checked and provenance-backed.

For local/private deployment routes, richer local-only analysis can be supported later through the same project-context contract.

Supplemental user context

The owner may provide additional:

• files/documents;
• links;
• screenshots/images;
• notes;
• product descriptions;
• existing project/brand guidance.

These remain canonical SourceArtifact/Asset/manual references where applicable. Project context stores stable refs/summaries/provenance, not copied secrets or arbitrary runtime objects.

Initial opportunities

Bootstrap must not invent a second “suggestions” state machine.

Initial content ideas should converge on the existing canonical path:

ProjectContext + bootstrap evidence
→ one or more canonical ContentSignal(s) when warranted
→ existing ContentOpportunity evaluation/ranking
→ Today / Plan judgment

Possible owner judgments include:

• start with this;
• see other angles;
• something else;
• later;
• not now;
• ignore/do not post.

No project is required to produce a post merely because onboarding completed.

“Not now” / returning-user behavior

If the owner chooses Not now:

• preserve exact project-context version and source provenance;
• preserve any canonical Signals/Opportunities according to lifecycle policy;
• do not create approval/publication state;
• do not force destination selection;
• return the user to a useful empty/decision-first state;
• on the next meaningful GitHub event, reuse the latest eligible project context automatically.

The owner should never need to reconnect/re-explain the project merely because the first content suggestion was deferred.

Context refresh/versioning

Repository understanding will become stale.

Required direction:

• immutable/versioned project-context snapshots;
• exact source/repository revision provenance;
• deterministic fingerprint or equivalent change identity;
• unchanged evidence reuses the current snapshot rather than duplicating it;
• meaningful repo/context change creates a new version;
• historical Signals/Opportunities/revisions keep references to the project-context version they actually used;
• new context never rewrites old content provenance.

Do not globally regenerate existing approved work when project context changes.

Automatic future trigger behavior

After a supported GitHub connection is active and bootstrap is successful:

future verified GitHub event
→ canonical ContentSignal
→ cheap noise gate
→ latest eligible ProjectContext snapshot
→ NarrativeMemory / repetition
→ existing Opportunity evaluation
→ only worthwhile/uncertain decisions surface

Default supported GitHub event families are product policy, not an onboarding questionnaire. Advanced controls can override later.

Destination/content-form boundary

This issue must not bake LinkedIn/X into repository understanding.

Destination/form/timing decisions remain downstream and can consider:

• owner preferred/connected destinations;
• current editorial calendar/cadence;
• story/platform fit;
• content form (text, image, carousel, Reel/Short, long-form, etc.);
• NarrativeMemory/repetition;
• media requirements;
• owner judgment.

The first useful onboarding moment may ask where the owner wants to start after useful stories exist, but destination setup must not block project understanding or Not now.

Application/domain boundaries

Implementation should preserve:

• pure/versioned domain record;
• repository port with memory/browser/store-backed adapters first;
• application service owns bootstrap/read/refresh decisions;
• UI/routes do not own repository scanning, persistence or inference calls;
• provider-neutral inference task if synthesis requires a model;
• bounded identity/project/source snapshots referenced by exact version IDs;
• no GitHub-specific fields in generic project context beyond canonical source provenance.

Security/privacy

• no raw GitHub access token, webhook secret, authorization header, signed URL or local filesystem path in ProjectContext;
• no unrestricted private patch/code body persisted as project summary;
• model payloads are task-minimized and privacy-route checked;
• logs/analytics use safe IDs/statuses only, not private repository/user content;
• revoked/disconnected source prevents new refresh/event processing;
• deleting a connection does not silently rewrite historical provenance.

First implementation slice

Build the source-neutral core before waiting for the complete GitHub App UX:

1. canonical/versioned project-context record;
2. repository port + memory/browser/store-backed adapters;
3. bootstrap application service from bounded repository evidence + optional supplemental source refs;
4. deterministic fingerprint/reuse/new-version behavior;
5. provider-neutral project-context synthesis task boundary where needed;
6. persistence/reopen tests;
7. Not now/defer semantics preserving context;
8. future Signal/Opportunity query can resolve the latest eligible context without duplicate state.

Then wire the GitHub installation path from #161 to invoke this automatically.

Acceptance criteria

• A new user can connect/provide one repository without configuring normal triggers/event families manually.
• Bounded repository evidence creates a canonical persisted project-context version with exact provenance.
• Optional user-provided context can contribute without duplicating source/asset payloads into the context record.
• Unchanged bootstrap input reuses the current context; meaningful changes create an immutable new version.
• First content suggestions use canonical Signal/Opportunity machinery rather than a second onboarding generator.
• A repo with no worthwhile story may truthfully produce no recommendation.
• Not now preserves project understanding and creates no approval/publication side effect.
• A later GitHub Signal automatically resolves/reuses prior eligible project context.
• Person Identity/Voice remains separate from project facts/context.
• Historical content keeps the exact project-context version it used.
• Private/secret/runtime data cannot enter the portable context record.
• Disconnect/revoke prevents new automatic refresh/event processing while historical provenance remains intact.
• Destination/content-form selection remains downstream and provider/source neutral.

Required verification

• public repo bootstrap;
• private/restricted-route fail-closed fixture;
• nested application/repository planner fixture;
• README-light repository fixture;
• supplemental owner note/document fixture;
• unchanged bootstrap idempotency;
• changed repository evidence → new context version;
• browser/store reconstruction;
• Not now then later meaningful Signal reuses context;
• no-content-worthy bootstrap;
• revoked connection;
• serialization/log redaction;
• stale/historical project-context provenance;
• source-neutral tests proving no LinkedIn/X assumptions.

Definition of done

Close only when a first-time user can connect/provide a repository, receive persistent bounded project understanding and useful canonical opportunities without learning SignalFlow trigger mechanics, defer all posting without losing context, and have later connected work automatically evaluated using that retained project understanding.