# Master app walkthrough and operating guide

> SYNTHETIC REFERENCE • SAMPLE-PENTASCOPE-MASTER • v1.0.0 • 2026-09-08 • Draft • all 96 cases Not Run. This is a proposed learning and acceptance pack, not customer source truth, test evidence or release approval. No project is created or seeded by opening it.

## Start with the reference reader

Open index.html or the app's `/samples/master-app/index.html` link. The page works offline, searches the test catalogue and prints with case steps expanded. Download Markdown for review, CSV for worksheet editing and JSON for structured inspection. The static reader has no login, API calls or project side effects. English is the complete reference language; Arabic examples and the concise walkthrough below support bilingual review.

## 1. Prepare and select your own project

In the actual application, start at `/en/login` for English or `/login` for Arabic. Sign in with your named account. Use `/en/projects` or `/projects` to create/select an authorized disposable test project. Verify its environment and base URL. Open its workspace/SRS and confirm it is empty before explicit source intake. Use separate named memberships from `/en/members` or `/members`; do not share owner tokens. A reviewer is a responsibility; membership roles are owner/editor/tester/viewer, with requirements-manager capability assigned through the allowed owner flow.

## 2. Adopt this sample deliberately

Read BRD.md, SRS.md and the gap register with the project owner. Make an adopted copy with project-specific facts, reviewers and approved scope. Bind source document IDs, versions and hashes after upload. Never treat the sample namespace or its local file references as an existing server-owned artifact. Import only into the disposable project you explicitly selected and authorized.

Typed source intake accepts BRD, SRS and test-case documents through `/api/project-documents`; the supported visible source-upload flow supplies the current request contract. Choose the correct type and a matching supported file format. The route currently limits documents to 20 MiB and checks MIME/extension/content. JSON/CSV in this pack are readable reference schemas; inspect normalization and mapping after intake rather than assuming direct API compatibility.

## 3. Review sources and detailed requirements

Use the SRS/source workspace (`/en/srs`, `/en/srs/document` and their Arabic routes) to inspect source type/hash, job status and findings. The backend analysis worker must be configured and running. Queued or failed jobs are not completed artifacts. Review the obligation ledger, every missing/contradictory rule, detailed actor/flow/data/permission acceptance and exact source links. Use a capability-authorized requirements manager for the permitted review transitions. Record changes as new revisions and inspect impact before reusing old approvals.

## 4. Design or import tests

Open the project's test-library view from the workspace. Review existing cases, map exact requirement/criterion IDs, preserve imported identity and resolve duplicate/unmapped cases. Generate only the requested missing coverage using governed backend tools. Inspect steps, data, expected result, role, cleanup and evidence. Test design does not run a browser or create proof. Approve only complete current designs through the permitted workflow; manual-only cases stay manual.

## 5. Prepare execution

Fill execution-manifest.json and resolve target/access/safety gaps. Record actual builds and a controlled data namespace. Configure credentials through the protected project flow and retain only secret-store references in the plan. Preview the selected current cases, review target/role/counts and explicitly confirm through the UI. If case approval, membership, credential or target changes, make a fresh preview. Missing setup blocks execution.

The operator/test lead surfaces are available at `/en/operator` and `/en/test-lead` (Arabic without `/en`). Agent integrations use a separately issued restricted key. The Chrome extension setup is at `/en/chrome-extension` only if that route exists in the adopted build; the source-discovered shared route is `/chrome-extension`. Use the actual visible navigation/current route map instead of guessing a locale alias.

## 6. Run, record and triage

Execute the precise adopted case with independent setup. Record actual observations in the row and step log, including exact build, UTC timestamps and sanitized evidence. Mark Passed only when the required oracle and evidence agree. A contradicted expectation is Failed; unavailable prerequisites are Blocked. Create a defect for an observed deviation, cite its criterion and run, then let the authorized human triage it.

## 7. Retest and decide readiness

Record the delivered fix build and delivery reference. Retest the linked case on that same build, preserve a new attempt and check impacted regression. Close only when the permitted evidence-backed gate is satisfied. Review designed, approved, executed and passed coverage independently; an unexecuted case remains unproven. A named release owner reviews open critical gaps and residual risk before sign-off.

## Role quick guide

- Product Owner: accept scope, assign memberships/capabilities, resolve decisions and review release risk.
- Business Analyst: preserve source obligations, refine detailed stories and map changes to downstream impact.
- Test Lead / tester: review cases, bind safe targets/data, observe runs, maintain evidence and retest.
- Editor / authorized reviewer: perform only capability-permitted content/decision actions; role title alone is not an approval bypass.
- Viewer: inspect project sources, coverage and authorized evidence; request an owner review when a needed mutation is unavailable.
- Operator: keep workers, database/storage and fixture services observable; distinguish readiness failure from liveness.
- Agent/Widget: execute or capture only the narrow service scope; never administer the project as a human.

## Troubleshooting

- Empty project: expected before an explicit normalized source import. Verify selected project and upload/job status; do not attach unrelated reference data to fill it.
- Upload rejected: confirm documentType, true format/MIME/extension, supported content and size. A renamed file is not converted by changing its extension.
- Analysis queued: inspect the actual job and local/backend worker readiness. The documented backend commands are `npm run analysis:watch` for bounded watching and `npm run analysis:dispatch` for one pass, run by the authorized operator with required configuration.
- AI unavailable: inspect sanitized policy/provider configuration and job error; do not fabricate a template as successful analysis. Local acceptance fixtures avoid paid calls.
- Approval unavailable: check requirements:manage, current state/version, unresolved findings and reviewer decision policy. Preserve the blocker.
- Preview blocked: inspect manual-only/Draft/stale cases, target and credential readiness. Review any ready-only selection explicitly.
- Evidence unavailable: confirm project access, actual file existence and signed-link expiry; request a fresh authorized link rather than exposing the storage key.
- Closure denied: compare delivered build, case lineage, computed retest outcome and evidence completeness. A passing unrelated run is insufficient.
- Locale/view mismatch: inspect current project context, route and refreshed backend result; preserve the observed UI error with a redacted screenshot.

## دليل عربي مختصر

هذه حزمة مرجعية اصطناعية بحالة مسودة؛ جميع الاختبارات لم تُنفّذ، ولا توجد أدلة نجاح أو اعتماد إصدار. افتح المشروع التجريبي المصرّح به بحسابك الشخصي، ثم ارفع مصدر BRD أو SRS بعد مراجعته. راجع المتطلبات والفجوات واربط كل معيار قبول بحالة اختبار واضحة. حدّد البيئة والإصدار والدور وبيانات الاختبار دون وضع كلمات المرور في المستند. سجّل الملاحظات الفعلية والأدلة عند التنفيذ؛ نقص المتطلبات يعني أن الاختبار محظور، وليس ناجحاً. لا تُغلق البلاغ قبل إعادة اختبار موثقة على نفس إصدار الإصلاح. الأدوار الفعلية هي المالك والمحرر والمختبر والمشاهد؛ المراجع مسؤولية وصلاحية عمل وليست دور عضوية مستقلّاً.

Arabic fixture strings: `مشروع الجودة التجريبي` (sample quality project), `لا يمكن للمشاهد تعديل المتطلبات` (viewer cannot edit requirements), and `الحد الأقصى 20 ميبيبايت` (20 MiB maximum). Preserve IDs and numeric limits during translation.

## Glossary

- BRD: business purpose, rules, scope and decisions.
- SRS: testable specification of actors, behavior, data and acceptance.
- Obligation: a distinct mandatory/prohibited source behavior needing disposition.
- Acceptance criterion: an observable condition proving part of a requirement.
- Traceability: explicit versioned links between source, requirement, criterion, case, run and evidence.
- Designed coverage: criteria linked to case designs; it is not observed behavior.
- Execution receipt: actual time, actor, step/assertion observation and evidence for a specific case/build.
- Build: the exact delivered revision being tested; environment name alone is not a build identity.
- Retest: a new observed run proving a defect's fix on its delivered build.
- Regression: selected related behavior rechecked because a change could affect it.
- Capability: server-enforced permission attached to a membership or restricted service scope.