Promote v0.260.028 from Development to Staging

.dockerignore

@@ -0,0 +1,33 @@
+# Keep ACR build context small and prevent local secrets/artifacts from being uploaded.
+**
+
+!application/
+!application/single_app/
+!application/single_app/**
+!docker-customization/
+!docker-customization/**
+
+.git/
+.github/
+.vscode/
+.azure/
+artifacts/
+deployers/
+docs/
+functional_tests/
+ui_tests/
+scripts/
+
+**/.env
+**/.env.*
+**/.venv/
+**/venv/
+**/__pycache__/
+**/.pytest_cache/
+**/*.pyc
+**/*.pyo
+**/*.pyd
+
+application/single_app/flask_session/
+application/single_app/uploaded_openapi_files/
+application/single_app/instance/

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,77 @@
+<!-- Thanks for contributing to SimpleChat! Keep this practical and delete sections that truly do not apply. -->
+
+## Summary
+
+<!-- What changed and why? Include the user/admin impact in 2-4 bullets. -->
+
+-
+-
+
+## Linked issue
+
+<!-- Use one when applicable: Fixes #123, Closes #123, Refs #123. -->
+
+Refs #
+
+## Release Notes & Latest Features
+
+<!-- Check the most relevant category. Release notes go under the current VERSION from application/single_app/config.py in docs/explanation/release_notes.md. -->
+
+- [ ] New Feature
+- [ ] Bug Fix
+- [ ] UI Enhancement
+- [ ] Breaking Change
+- [ ] Internal only
+
+Is this visible to end users?
+
+- [ ] Yes
+- [ ] No
+
+Is this admin-facing (Admin Settings, governance, deployment, config)?
+
+- [ ] Yes
+- [ ] No
+
+Should this become a Latest Feature card?
+
+- [ ] Yes
+- [ ] No
+- [ ] Already added
+
+Screenshot needed for the card?
+
+- [ ] Yes
+- [ ] No
+- [ ] Attached
+
+## Version bump
+
+<!-- Confirm application/single_app/config.py VERSION patch segment was bumped for code changes. If deployers/ changed, also bump deployers/version.txt. -->
+
+- [ ] `application/single_app/config.py` `VERSION` third segment bumped, or not needed because this is docs-only
+- [ ] `deployers/version.txt` bumped, or not needed because `deployers/` was not changed
+
+## Testing / validation
+
+<!-- List commands run and any manual validation. -->
+
+-
+-
+
+## Documentation
+
+<!-- Feature docs: docs/explanation/features/. Fix docs: docs/explanation/fixes/. -->
+
+- [ ] Release notes updated, or not needed
+- [ ] Feature documentation updated, or not needed
+- [ ] Fix documentation updated, or not needed
+
+## Security checklist
+
+<!-- These are common SimpleChat review requirements. -->
+
+- [ ] New Flask routes include `@swagger_route(security=get_auth_security())`
+- [ ] Settings sent to non-admin frontends use `sanitize_settings_for_user()`
+- [ ] Browser JavaScript is served from local SimpleChat static assets only; no CDN-hosted JS
+- [ ] No secrets, keys, connection strings, or local-only artifacts are included

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    groups:
+      github-actions:
+        patterns: ["*"]
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7

.github/instructions/docs_coverage.instructions.md

@@ -0,0 +1,104 @@
+---
+applyTo: '**'
+---
+
+# Documentation Coverage
+
+## Why this exists
+
+The documentation site is kept in sync with the application by a generated
+inventory plus tests. Before this was in place, coverage decayed silently: the
+app had 111 capability toggles, 18 admin settings tabs, 27 action plugins, and
+47 chat controls while the docs described roughly a dozen capabilities and had
+no per-tab, per-action, or per-control reference at all.
+
+## The rule
+
+When a change adds or renames any of the following, the same change must update
+the documentation:
+
+| You added or renamed | Document it in |
+|---|---|
+| An `enable_*` settings key | The relevant `docs/admin/<tab>.md` settings table, and claim the key in `docs/_data/features.yml` |
+| An admin settings tab | A new `docs/admin/<tab-id>.md` page |
+| A Semantic Kernel action plugin | A new `docs/reference/actions/<slug>.md` page |
+| A chat UI control | `docs/reference/chat-controls.md` |
+| A user-facing app page or major surface | A guide under `docs/guides/` |
+
+## Regenerating the inventory
+
+The application surface inventory is generated, not hand-written:
+
+```powershell
+python .\scripts\build_docs_inventory.py
+```
+
+This writes `docs/_data/app_surface.yml`. Commit the regenerated file with your
+change. The inventory deliberately does not record the application version, so
+it only changes when the application surface actually changes.
+
+## Verifying
+
+```powershell
+python .\functional_tests\test_docs_app_surface_coverage.py
+python .\functional_tests\test_docs_site_quality.py
+```
+
+The coverage test fails when any inventory item is undocumented, and when the
+committed inventory is stale relative to the application.
+
+## Internal-only flags
+
+A settings key that has no admin-facing UI and is purely an internal rollout,
+telemetry, or tuning switch may be exempted. Add it to `CAPABILITY_EXEMPTIONS`
+in `functional_tests/test_docs_app_surface_coverage.py` **with a written
+justification**. Exemptions are themselves checked for staleness, so a flag that
+is later removed from the application will fail the test until the exemption is
+deleted.
+
+Do not use an exemption to avoid writing documentation for a user-facing
+capability.
+
+## Screenshots and videos
+
+Documentation pages declare media slots that render a visible placeholder card
+until the asset exists. To add a screenshot, save the file at the exact path the
+placeholder names, for example `docs/images/admin/general-tab.png`. No YAML or
+code change is required.
+
+Videos are never committed to the repository. Upload the recording to YouTube or
+Microsoft Stream, save a poster frame under `docs/images/video-posters/`, and add
+the watch URL to the slot in `docs/_data/media.yml`.
+
+Outstanding media is listed at `/contributing/media-status/`. Missing media does
+not fail the build, so it never blocks a change, but it stays visible.
+
+## Writing quality
+
+Documentation pages must explain **what a capability does and why someone would
+use it**, not restate control names.
+
+Do not write:
+
+- "Turns X on or off" or "Sets X" as a description.
+- The same boilerplate paragraph across multiple sections or pages.
+- Procedures that only describe using a form, such as "Open the page, change the
+  fields, save".
+- Prerequisites that would apply to any page.
+
+Never invent a setting, default, field, or behavior. A shorter accurate page is
+better than a longer speculative one.
+
+## Page structure
+
+Write plain markdown with real `##` and `###` headings. The site generates its
+"On this page" table of contents and heading anchors from rendered `h2`/`h3`
+elements, so pages authored as HTML card markup get neither. Do not add
+`<section>`, `<div>`, or card/badge markup to documentation pages.
+
+## Browser assets
+
+The documentation site loads no third-party assets. Everything is vendored under
+`docs/assets/vendor/` and pinned by version. Do not add a CDN `<script>`,
+`<link>`, `@import`, or webfont URL to any docs layout, include, stylesheet, or
+page. See `local_browser_assets.instructions.md`.

.github/instructions/github_issue_workflow.instructions.md

@@ -0,0 +1,52 @@
+---
+applyTo: '**'
+---
+
+# GitHub Issue Workflow
+
+## When Starting Work
+
+At the start of meaningful work, determine whether there is an associated GitHub issue for the task.
+
+- If the user mentions an issue number or URL, treat that as the associated issue and keep it in mind for summaries, PR notes, release notes, and later status updates.
+- If no issue is mentioned and the work is more than a tiny clarification or one-off command, ask the admin whether they want to create an issue before or alongside the work.
+- If the admin wants an issue created, use the existing `Create GitHub Issue` prompt in `.github/prompts/create-github-issue.prompt.md`.
+- Do not block urgent fixes, small investigations, or explicitly time-sensitive work just because there is no issue yet. Continue the work and ask at the next natural checkpoint.
+
+## Issue Association
+
+When an issue exists or is created for the work:
+
+- Track it as the working associated issue for the current task.
+- Reference the issue in relevant summaries, PR descriptions, fix documentation, feature documentation, and release note entries when appropriate.
+- Prefer durable references such as `Fixes #123`, `Closes #123`, or `Refs #123` when the change directly resolves, completes, or relates to the issue.
+- Do not create duplicate issues. Use the issue creation prompt's duplicate-search workflow before creating a new issue.
+
+## When To Suggest Updating Issues
+
+Prompt the admin to update the associated issue at natural checkpoints, not on every interaction.
+
+Ask whether to update the associated issue when any of these occur:
+
+- The implementation is complete or materially changes direction.
+- Important validation results are available.
+- Scope, priority, acceptance criteria, or user impact changes.
+- A blocker, dependency, risk, or follow-up task is discovered.
+- Release notes are being updated or the admin is asked whether to update release notes.
+
+Use concise wording such as:
+
+> Would you like me to update the associated GitHub issue with the summary, validation, and any follow-ups from this work?
+
+If there is no associated issue at one of these checkpoints, ask whether the admin wants to create one using the `Create GitHub Issue` prompt.
+
+## What To Put In Issue Updates
+
+When the admin approves an issue update, include only useful status information:
+
+- What changed.
+- Current validation status and relevant test results.
+- Any unresolved risks, blockers, or follow-ups.
+- Links or references to related PRs, documentation, or release notes when available.
+
+Do not post noisy progress comments, implementation chatter, or repeated updates that do not change the issue's useful state.

.github/instructions/include_config_version_in_functional_test_files.instructions.md

@@ -39,7 +39,19 @@ When implementing fixes or features:
 3. Include this version in documentation markdown files
 4. Ensure consistency across all related files
 
-### 4. Version Tracking Benefits
+### 4. Version Assertions in Tests
+
+Functional tests must not assert the current `config.py` version with exact equality, because exact checks fail after normal future version bumps. When a test needs to prove that a fix or feature is present in at least its implementation version, use the shared helper:
+
+```python
+from test_support.versioning import assert_app_version_at_least
+
+assert_app_version_at_least("0.250.126")
+```
+
+Keep exact version literals only when the version itself is test data, such as validating version-comparison behavior or historical documentation text.
+
+### 5. Version Tracking Benefits
 - Clear traceability of when fixes/features were implemented
 - Easy identification of test coverage for specific versions
 - Simplified debugging and rollback procedures

.github/instructions/location_of_functional_tests.instructions.md

@@ -6,12 +6,14 @@ applyTo: '**'
 
 ## 📍 **Location**
 All functional tests are stored in: `.\simplechat\functional_tests\`
+Check local.instructions.md for any additional instructions on test creation, execution, and maintenance.
 
 ## 📂 **Directory Structure**
 The functional tests directory contains:
 - **Python test files** (`test_*.py`) - Executable test scripts
 - **JavaScript test files** (`test_*.js`) - Client-side/browser test scripts  
 - **Documentation files** (`*.md`) - Test documentation and fix summaries
+- **route_tests/** - Route registration, Blueprint policy, and unauthenticated access contract tests
 - **flask_session/** - Session data for tests requiring authenticated state
 
 ## 🎯 **When to Create Functional Tests**
@@ -25,6 +27,12 @@ The functional tests directory contains:
 ✅ **UI/UX Changes** - Test display logic, user interactions, data flow  
 ✅ **Authentication/Security** - Verify access controls and data isolation  
 
+### **Always Update Route Tests For:**
+✅ **New Flask Routes** - Add the route to `functional_tests/route_tests/` policy coverage
+✅ **Route Moves or Renames** - Update Blueprint policy and endpoint-name expectations
+✅ **Auth Policy Changes** - Update unauthenticated access expectations and role-policy checks
+✅ **Public or External Routes** - Add explicit public/bearer-token policy entries and justify them in the tests
+
 ### **Test Categories:**
 - **Integration Tests** - End-to-end functionality across multiple components
 - **Regression Tests** - Prevent previously fixed bugs from returning
@@ -184,6 +192,7 @@ test_config = {
 - **Plugin Integration Tests** → `functional_tests/` (follow `test_openapi_*.py` patterns)
 - **Migration Tests** → `functional_tests/` (follow `test_migration.py` pattern)
 - **UI/Display Tests** → `functional_tests/` (follow `test_*_display.py` patterns)
+- **Route Policy Tests** → `functional_tests/route_tests/` for Blueprint registration, route security policy inventory, and unauthenticated access contracts
 
 ### **Documentation Requirements:**
 - **For Bug Fixes**: Create accompanying `.md` file describing the issue and solution
@@ -205,6 +214,11 @@ for test in test_*.py; do python $test; done
 
 # Run specific test pattern  
 python test_openapi_*.py
+
+# Run route policy coverage tests
+python route_tests/test_route_blueprint_policy_inventory.py
+python route_tests/test_route_unauthenticated_policy_contract.py
+python route_tests/test_route_policy_test_coverage.py
 ```
 
 ### **Integration with Development Workflow:**
@@ -230,4 +244,4 @@ python test_openapi_*.py
 ### **Maintenance:**
 ✅ **Regular Review** - Periodically review and update tests for relevance  
 ✅ **Refactoring** - Extract common patterns into reusable utilities  
-✅ **Documentation Updates** - Keep test documentation current with code changes
+✅ **Documentation Updates** - Keep test documentation current with code changes

.github/instructions/python-lang.instructions.md

@@ -19,7 +19,7 @@ applyTo: '**/*.py'
 
 - Code and definitions should occur after the imports block.
 
-- All logging should used tag based prefixes. Ex: [GPTClient] or [SKLoader] to identify the source of the log message and make it easier to trace. Tags should be enclosed in square brackets. Tags should be generalized to the operation that is occurring. Any existins logging that is missing tags should have tags added.
+- All logging should use tag-based prefixes. Ex: `[GPT_CLIENT]` or `[SK_LOADER]` to identify the source of the log message and make it easier to trace. Tags should be enclosed in square brackets and MUST use `UPPERCASE_WITH_UNDERSCORES`. Tags should be generalized to the operation that is occurring. Prefer static tags; move dynamic values into the message body or `extra` metadata instead of embedding them inside the bracketed tag. Any existing logging that is missing tags should have tags added. When adding or renaming a logging tag, update `docs/reference/logging-tags.md` in the same change so the reference inventory stays current.
 
 - Always import `log_event` from `functions_appinsights.py` for any logging activities.
 
@@ -31,10 +31,18 @@ applyTo: '**/*.py'
 
 - Files with routes MUST import `from swagger_wrapper import swagger_route, get_auth_security` and use the `@swagger_route(security=get_auth_security())` decorator for all route functions.
 
+- New Flask routes MUST be registered on a `Blueprint`, not directly on `app`. Use `Blueprint(...).route(...)` or pass a `Blueprint` into the route module registrar. Do not add new `@app.route(...)` routes except for a reviewed framework/bootstrap exception.
+
+- Each route-owning Blueprint MUST have an explicit `before_request` security policy using the shared helpers in `functions_authentication.py`, such as `login_required_blueprint()`, `user_required_blueprint()`, `admin_required_blueprint()`, or `external_api_required_blueprint()`. Mixed-policy Blueprints may use a login-only Blueprint guard and keep stricter route-specific decorators such as `@user_required`, `@admin_required`, `@control_center_required(...)`, `@feedback_admin_required`, or `@safety_violation_admin_required` on individual routes.
+
+- Every route change MUST update or verify the route coverage tests in `functional_tests/route_tests/`. At minimum, run `python functional_tests/route_tests/test_route_blueprint_policy_inventory.py`, `python functional_tests/route_tests/test_route_unauthenticated_policy_contract.py`, and `python functional_tests/route_tests/test_route_policy_test_coverage.py` after adding, moving, or changing routes.
+
 - When editing group workspace content, always use the `assert_group_role(user_id, group_id, allowed_roles=("Owner", "Admin", "DocumentManager", "User"))` function to verify the user's current membership and role in the group before allowing access to group-scoped resources or operations. This ensures that users cannot access or modify group content based solely on a potentially stale or tampered `activeGroupOid` reference. Roles should vary based on the level of access required for the operation, but should always include "Owner" and "Admin" as allowed roles.
 
-- Unless otherwise indicated, all routes MUST include `@login_required` decorator. 
+- Unless otherwise indicated, all protected routes MUST be covered by a Blueprint-level login policy and/or an explicit route-level `@login_required` decorator. Public and external bearer-token routes must be listed in the route policy tests with their expected unauthenticated behavior.
 
 - Always use f-strings for string interpolation. Ex: `f"User ID: {user_id}"` instead of `"User ID: {}".format(user_id)"`
 
-- Never use `except:` without specifying the exception type. Always catch specific exceptions or use `except Exception as ex:` to capture the exception details. This also avoids accidentally catching system-exiting exceptions like `KeyboardInterrupt` or `SystemExit`.
+- Never use `except:` without specifying the exception type. Always catch specific exceptions or use `except Exception as ex:` to capture the exception details. This also avoids accidentally catching system-exiting exceptions like `KeyboardInterrupt` or `SystemExit`.
+
+- Never return raw exception text to browser or API clients. Do not use `str(e)`, `str(exc)`, `repr(e)`, traceback text, SDK exception messages, connection strings, or provider errors in `jsonify()`, template rendering, streaming responses, or other client-visible payloads. Log exception type and safe contextual metadata server-side with `log_event` or `debug_print`, then return a stable user-safe message such as `"Invalid request."`, `"Unable to save action."`, or `"Unable to store secrets in Key Vault."`

.github/instructions/update_release_notes.instructions.md

@@ -10,6 +10,8 @@ After completing a code change (bug fix, new feature, enhancement, or breaking c
 
 **"Would you like me to update the release notes in `docs/explanation/release_notes.md`?"**
 
+When asking this, also ask whether the associated GitHub issue should be updated. If there is no associated issue, ask whether the admin wants to create one using `.github/prompts/create-github-issue.prompt.md`.
+
 ## If the User Confirms Yes
 
 Update the release notes file following these guidelines: