🔤 Ups docs to current state

README.md

@@ -1,13 +1,49 @@
+# CommaFeed Podcasts
+
 <p align="center">
-  <img width="200" src="./assets/logo.svg"></img>
+  <img width="200" src="./src/assets/logo.svg" alt="CommaFeed Podcasts logo">
 </p>
 
-# CommaFeed Podcasts
-**Experimantal/WIP** PWA podcast app. Idea is to use [CommaFeed](https://github.com/Athou/commafeed) as a backend.
+> **Experimental / WIP** – A progressive web application for podcast consumption, powered by [CommaFeed](https://github.com/Athou/commafeed) as the backend.
 
+## Links
 - [Plan](./changelog/PLAN.md), [Task](./changelog/TASK.md)
-- [Building scripts](./bs/README.md)
 - [![Built with open-wc recommendations](https://img.shields.io/badge/built%20with-open--wc-blue.svg)](https://github.com/open-wc)
 - [What is Lit? – Lit](https://lit.dev/docs/)
 - [@lit-labs/router - npm](https://www.npmjs.com/package/@lit-labs/router)
 - [lit-translate - npm](https://www.npmjs.com/package/lit-translate)
+
+## Features
+- **PWA** support with offline caching.
+- Client‑side routing via a lightweight router.
+- Dynamic page rendering based on URL parameters (e.g., `/episodes/:id`).
+- Built with Lit, TypeScript and Open‑WC tooling.
+
+## Getting Started
+```bash
+npm install
+bs/start
+```
+
+## Build Scripts
+See [bs/README.md](./bs/README.md) for available build and deployment scripts.
+
+## Testing
+Tests are written with `@open-wc/testing` (Mocha) / Web Test Runner and follow the `*.test.ts` convention. Run all tests via:
+```bash
+bs/test
+```
+
+## Documentation
+- Overall development plan: [docs/dev/PLAN.md](./docs/dev/PLAN.md)
+- Overall task board: [docs/dev/TASK.md](./docs/dev/TASK.md)
+- App source overview: [src/README.md](./src/README.md)
+
+## Contributing
+TBD
+<!--
+Pull requests are welcome! Please read the contributing guidelines in `CONTRIBUTING.md` (if present) or open an issue to discuss major changes.
+-->
+
+## License
+[MIT](LICENSE)

src/README.md

@@ -0,0 +1,63 @@
+# CommaFeed Podcasts – Web Component/App
+
+This repository contains the **source code** for a small progressive web application built with Lit and Open‑WC recommendations.
+
+## High‑level structure
+
+### Pages (`app-*`, `index.ts`, `*.css.ts`, `*.test.ts`)
+Folder naming (`app-name`) corresponds to custom element name (`<app-name>`) and endpoint (`/name`).
+Dynamic parameters are supported using `:` in the name (`app-:id`/`<app-episode id=${id}>`/`/episodes/:id`).
+
+Each folder follows a consistent pattern:
+
+1. **Page component file** – `index.ts` contains the Lit component definition.
+1. **Styles** – `*.css.ts` holds the scoped CSS for that component.
+1. **Tests** – optional `*.test.ts` hoding overall app router tests (probably integration test).
+1. **Routing helper** – optional `routes.ts`
+1. **README** – describes the module’s purpose and key files.
+
+Below is an overview of the current pages:
+
+- [`<app-home>`](./app-home)
+- [`<app-episodes>`](./app-episodes)
+
+*(More feature modules can be added in the future following the same pattern.)*
+
+### Components (`src/components/`, `*.css.ts`, `*.test.ts`)
+The `components/` folder contains re‐usable UI building blocks shared across feature modules.
+
+- file naming: `c-name` (files `c-name.ts` and `c-name.css.ts`)
+- folder follows the same pattern as pages (except no routes)
+
+### Core (`src/core/`, `*.test.ts`)
+The `core/` folder contains routing and translation infrastructure, and shared utilities.
+
+The `*.test.ts` files are used for unit tests for given core file.
+
+### Assets (`src/assets/`)
+The `assets/` folder contains static files (logos, icons, etc.) that are imported by components.
+
+Use `new URL('/assets/logo.png', import.meta.url)` to get the URL of a static file.
+
+## How routing works
+The application uses a lightweight client‑side router (see `core/routes.ts`).
+Route definitions look like:
+
+```ts
+import { route } from "@/core/route.js";
+import { html } from "lit";
+
+export const path = "/episodes/" as const;
+export const routes = route(
+	{
+		path: "/episodes/:id/",
+		async enter() {
+			await import("./index.js");
+			return true;
+		},
+		render({ id }){
+			return html`<app-episode id=${id}></app-episode>`;
+		},
+	},
+);
+```

src/app-episodes/README.md

@@ -0,0 +1,8 @@
+# `<app-episodes>`
+
+Displays a list of podcast episodes.
+
+## Subroutes
+
+### `<app-:id>`
+The component is routed to via `/episodes/:id?` where `:id` is an optional episode identifier used to show a specific episode.

src/app-episodes/routes.ts

@@ -1,5 +1,5 @@
 import { route } from "@/core/route.js";
-import { routes as routeEpisode } from "./:id/routes.js";
+import { routes as routeEpisode } from "./app-:id/routes.js";
 import { html } from "lit";
 
 export const path = "/episodes/" as const;

src/app-home/README.md

@@ -0,0 +1,7 @@
+# app‑home
+
+This feature module implements the home page of the podcast application and handles navigation logic.
+
+## Files
+- `index.ts` – Lit component that renders the landing view.
+- `router.js` (if any) – Routing helpers for navigating between pages.

src/index.ts

@@ -23,13 +23,14 @@ export class AppCfpodcasts extends LitElement {
 			<nav>
 				<a
 					href="${this._routes.link("/")}"
-					title="Home"
+					title="Navigate to the home page"
 					>
 					<img alt="" src=${logo} />
 					<c-sronly>Home</c-sronly>
 				</a>
 				<a
 					href="${this._routes.link(routeEpisodes.path)}"
+					title="Navigate to the list of episodes"
 					>
 					Episodes
 				</a>