# Portal Resource List Governance

Version 1.0 | 2026-05-15

## Purpose

The Software Portal should be a curated access point, not an automatic mirror of every GitHub repository. Each visible item must be intentionally approved because it is useful for Cold Electric team members.

## Source of Truth

The approved list is maintained in `data/resources.json`.

When the portal is served over HTTP, `index.html` fetches `data/resources.json` at runtime. If someone opens `index.html` directly with `file://`, the page uses embedded fallback data for preview only.

The portal can include multiple resource types:

| Type | Usage |
| :--- | :---- |
| `github_repo` | Software repositories that team members need to find or access |
| `google_doc` | Google Docs, Sheets, Slides, or Drive folders |
| `production_app` | Live services such as Nexus or public websites |
| `local_doc` | Documentation files stored in this repository |
| `external_url` | Other approved tools, dashboards, or references |

## Approval Rules

- Only resources with `"approved": true` are shown in the portal.
- Resources with `"approved": false` can remain in the JSON as candidates, but must not render in the public grid.
- Every approved resource needs an owner, category, status, and at least one URL.
- GitHub repositories are not approved by default. Add them only when the portal audience needs them.
- Google Docs must use shared links that are accessible to the intended Cold Electric audience.
- Deprecated repositories should usually remain unapproved unless they are needed for migration or reference work.

## Required Fields

```json
{
  "id": "stable-slug",
  "type": "github_repo",
  "approved": true,
  "owner": "Engineering",
  "name": "EMS Dashboard",
  "name_zh": "EMS 能源管理儀表板",
  "description": "BESS monitoring and management platform.",
  "description_zh": "商用儲能系統監控與管理平台。",
  "categories": ["operations", "engineering"],
  "status": "production",
  "primary_url": "https://nexus.coldelectric.com",
  "repo_url": "https://github.com/realcoldelectric/ems-dashboard",
  "docs_url": null,
  "tags": ["React", "Supabase"],
  "updated_at": "2026-05-15"
}
```

## Manual Update Workflow

1. Add or edit an entry in `data/resources.json`.
2. Set `"approved": false` for draft or candidate resources.
3. Ask the relevant owner to review the label, description, audience, and URL access.
4. Set `"approved": true` after approval.
5. Open the portal locally and verify search, role tabs, language labels, and links.

Use a local HTTP server for verification:

```bash
python3 -m http.server 8080
```

Then open `http://localhost:8080/`.

## Review Checklist

- The resource helps a defined audience: Business, Operations, Engineering, or JC Star.
- The Traditional Chinese and English labels are both present.
- The URL opens for the intended users.
- The status is accurate: `production`, `active`, `staging`, `testing`, `reference`, `legacy`, or `archived`.
- The resource follows Cold Electric brand guidance: professional tone, no emoji, and clear naming.